README for Shared Makefiles

[texastony]

The Shared Makefiles are pretty much the only way to use Smithy-Dafny and Dafny at scale.

However, they lack documentation.

Recently, I struggled to re-polymorph my project, running into a patch cannot be applied error.

I figured out a work around, which I think should be recorded somewhere, along with at least some general guidance on the top-level make recipes of the Shared Makefiles.

[texastony]

Super casual instructions to resolve patch cannot be applied error:

1. move the failing patch out of the codegen-patches directory: git mv codegen-patches/<Namespace, ie: AwsCryptographyKeyStore>/<runtime, ie: dotnet>/dafny-4.2.0.patch $(git rev-parse --show-toplevel)/temp.path
2. Run make polymorph_code_gen DAFNY_VERSION=4.2.0 , which will now succeed, since it will not fail to apply the patch
3. stage the generated code: git add .
4. Make the manual changes you need in a particular runtime & namespace (i.e: .net/KeyStore). Consult the patch files you moved to temp.path in step 1 to determine what the manual changes are.
5. Persist the manual changes in a patch git diff > codegen-patches/<Namespace, ie: AwsCryptographyKeyStore>/<runtime, ie: dotnet>/dafny-4.2.0.patch
6. Stage the patch: git add <changed-files-runtime-namespace> codegen-patches
7. Go to Step 4 for the next runtime & namespace, until all runtime & namespaces are exhausted
8. Finally, commit all the changes: git commit -m "polymorph is a good idea but needs some manual effort"

These steps are necessary when:

• Benerating a new fix
• Re-polymorphing a model that, even if it was only changed in minor ways, results in a substantial git diff that invalidates the patches.

[texastony]

I have had significant success with using gmake from Home Brew to determine Make recipes. My gmake is much better than the make that came installed on my Mac.