Docs and copy-editing of text

.gitignore

@@ -18,3 +18,12 @@ _opam/
 /.ci/dkml-compilers/gh-*
 #   Desktop testing on Windows uses MSYS2.
 /msys64/
+
+# --inplace-build
+/_w/
+/dkmldir/
+/dl/homebrew/
+/dl/homebrew-bundle/
+/dl/opam/
+/dl/*.tar.gz
+/Brewfile

DEVELOPMENT.md

@@ -13,7 +13,12 @@ opam install ./dkml-component-offline-opamshim.opam --keep-build-dir --yes
 On Unix:
 
 ```sh
-opam switch create . --repos 'default,diskuv-2.0.3=git+https://github.com/diskuv/diskuv-opam-repository.git#2.0.3'
+opam switch create . --no-install --repos 'default,diskuv-2.1.0=git+https://github.com/diskuv/diskuv-opam-repository.git#2.1.0'
+
+# You can install just what is needed for https://github.com/diskuv/dkml-installer-opam
+opam install ./dkml-component-common-opam.opam ./dkml-component-staging-opam32.opam ./dkml-component-staging-opam64.opam ./dkml-component-offline-opam.opam --keep-build-dir --yes
+
+# Or install everything
 opam install . --deps-only --with-test --yes
 opam install ./dkml-component-offline-opamshim.opam --keep-build-dir --yes
 ```

README.md

@@ -1,17 +1,84 @@
-# staging-opam32, staging-opam64 and offline-opam
+# opam components distributed by DkML
+
+## Making a new version
+
+> It is perfectly fine to do all of this on a Unix machine, even if you intend to distribute to Windows users.
+
+> The following assumes you have a Unix shell. On Windows with DkML installed you can use `with-dkml bash` to get one.
+
+1. Do the following parts of the Prereqs section in [DEVELOPMENT.md](./DEVELOPMENT.md):
+
+   ```sh
+   # On Windows
+   dkml init
+
+   # On Unix
+   opam switch create . --no-install --repos 'default,diskuv-2.1.0=git+https://github.com/diskuv/diskuv-opam-repository.git#2.1.0' --packages dkml-base-compiler.4.14.0~v2.1.0
+   ```
+2. Edit the `(version ...)` in [dune-project](./dune-project).
+   There are guidelines in that file, especially about including the date in the version string.
+3. Add an entry to [CHANGES.md](./CHANGES.md).
+4. Add a new opam version inside `extra-source "dl/opam.tar.gz"` in [dkml-component-staging-opam64.opam.template](./dkml-component-staging-opam64.opam.template) and [dkml-component-staging-opam32.opam.template](./dkml-component-staging-opam32.opam.template).
+   - Update the `src` and `checksum` fields. The `src` should be the "Source code (tar.gz)" asset link for the latest release in https://github.com/ocaml/opam/releases (or better yet use a permanent download link).
+   - **Update the changelog comments in this section.** That means you clone the *new* `src` and `checksum` fields as *comments*.
+5. Do:
+
+   ```sh
+   opam exec -- dune build *.opam
+   git add CHANGES.md dune-project *.opam *.opam.template
+   git commit -m "Prepare new version (1/2)"
+
+   opam remove dkml-component-staging-opam64 -y
+   opam install ./dkml-component-staging-opam64.opam --keep-build-dir
+   ```
+6. You will need to place the output of the following command into the **BEGIN OPAM ARCHIVES** sections of [dkml-component-staging-opam64.opam.template](./dkml-component-staging-opam64.opam.template) and [dkml-component-staging-opam32.opam.template](./dkml-component-staging-opam32.opam.template):
+
+   ```sh
+   opamdl="$(opam var dkml-component-staging-opam64:build)/dl/opam"
+
+   join <(awk '$1~/^URL_[a-z]/{sub(/URL_/,"",$1); print $1,"URL",$NF}' "${opamdl}/src_ext/Makefile" "${opamdl}/src_ext/Makefile.sources") <(awk '$1~/^MD5_[a-z]/{sub(/MD5_/,"",$1); print $1,"MD5",$NF}' "${opamdl}/src_ext/Makefile" "${opamdl}/src_ext/Makefile.sources") | awk -v dq='"' '$2=="URL" && $4=="MD5"{name=$3; sub(".*/", "",name); printf "extra-source %sdl/opam/src_ext/archives/%s%s {\n  src: %s%s%s\n  checksum: [\n    %smd5=%s%s\n  ]\n}\n", dq,name,dq, dq,$3,dq, dq,$5,dq }'
+   ```
+7. Do:
+
+   ```sh
+   opam exec -- dune build *.opam
+   git add CHANGES.md dune-project *.opam *.opam.template
+   git commit -m "Prepare new version (2/2)"
+
+   opam install ./dkml-component-common-opam.opam ./dkml-component-staging-opam32.opam ./dkml-component-staging-opam64.opam ./dkml-component-offline-opam.opam --keep-build-dir --yes
+
+   # See some important OS-specific files that will be packaged as part of the installer
+   find "$(opam var dkml-component-offline-opam:share)/staging-files"
+   find "$(opam var dkml-component-staging-opam64:share)/staging-files"
+   ```
+
+8. Do:
+
+   ```sh
+   # 2.2.0~beta2~20240409 is tagged as 2.2.0-beta2-20240409
+   tagversion=$(awk '/\(version / { sub(/)/, ""); gsub(/~/, "-"); print $2 }' dune-project)
+   git tag "$tagversion"
+   git push origin "$tagversion"
+   ```
+
+That should kick of GitHub Actions which will build for Windows, macOS and Linux.
+
+**FINALLY**, start at step 2 of [dkml-installer-opam's "Making a new version"](https://github.com/diskuv/dkml-installer-opam?tab=readme-ov-file#making-a-new-version) to complete the instructions for publishing so `winget install opam` picks up your changes.
+
+## Components: staging-opam32, staging-opam64 and offline-opam
 
 The `staging-opam32` and `staging-opam64` components make available the Opam binaries (`opam`, `opam-installer`
-and on Windows `opam-putenv`) in the staging-files directory.
+and on Windows `opam-putenv`) in the `staging-files` directory.
 
 The `offline-opam` component will install the Opam binaries from `staging-opam32` on 32-bit machines into
 the end-user's installation prefix, and from `staging-opam64` on 64-bit machines.
 
 These are components that can be used with [dkml-install-api](https://diskuv.github.io/dkml-install-api/index.html)
-to generate installers.
+to generate the `winget` / `setup.exe` installers.
 
 ## dkml-component-staging-opam32 and dkml-component-staging-opam64
 
-These components vary by whether distribute 32-bit or 64-bit executables. Sometimes
+DkML components vary by whether 32-bit or 64-bit executables are distributed. Sometimes
 we only distribute 64-bit for a host operating system (ex. macOS).
 
 ### Executables

dkml-component-common-opam.opam

@@ -1,10 +1,10 @@
 # This file is generated by dune, edit dune-project instead
 opam-version: "2.0"
 version: "2.2.0~alpha0~20221228-r3"
-synopsis: "Common code for opam DKML components"
-description: "Common code for opam DKML components"
-maintainer: ["opensource+diskuv-ocaml@support.diskuv.com"]
-authors: ["Diskuv, Inc. <opensource+diskuv-ocaml@support.diskuv.com>"]
+synopsis: "Common code for opam DkML components"
+description: "Common code for opam DkML components"
+maintainer: ["opensource+dkml@support.diskuv.com"]
+authors: ["Diskuv, Inc. <opensource+dkml@support.diskuv.com>"]
 license: "Apache-2.0"
 homepage: "https://github.com/diskuv/dkml-component-opam"
 bug-reports: "https://github.com/diskuv/dkml-component-opam/issues"

dkml-component-offline-opam.opam

@@ -23,8 +23,8 @@ sufficient to be compatible with semver and winget version ordering.
 
 Includes a patch to distinguish MSYS2 from Cygwin, esp. for rsync rather than symlinking which is needed on MSYS2.
 """
-maintainer: ["opensource+diskuv-ocaml@support.diskuv.com"]
-authors: ["Diskuv, Inc. <opensource+diskuv-ocaml@support.diskuv.com>"]
+maintainer: ["opensource+dkml@support.diskuv.com"]
+authors: ["Diskuv, Inc. <opensource+dkml@support.diskuv.com>"]
 license: "Apache-2.0"
 homepage: "https://github.com/diskuv/dkml-component-opam"
 bug-reports: "https://github.com/diskuv/dkml-component-opam/issues"

dkml-component-offline-opamshim.opam

@@ -28,8 +28,8 @@ sufficient to be compatible with semver and winget version ordering.
 
 Includes a patch to distinguish MSYS2 from Cygwin, esp. for rsync rather than symlinking which is needed on MSYS2.
 """
-maintainer: ["opensource+diskuv-ocaml@support.diskuv.com"]
-authors: ["Diskuv, Inc. <opensource+diskuv-ocaml@support.diskuv.com>"]
+maintainer: ["opensource+dkml@support.diskuv.com"]
+authors: ["Diskuv, Inc. <opensource+dkml@support.diskuv.com>"]
 license: "Apache-2.0"
 homepage: "https://github.com/diskuv/dkml-component-opam"
 bug-reports: "https://github.com/diskuv/dkml-component-opam/issues"

dkml-component-staging-opam32.opam

@@ -1,7 +1,7 @@
 # This file is generated by dune, edit dune-project instead
 opam-version: "2.0"
 version: "2.2.0~alpha0~20221228-r3"
-synopsis: "DKML component for 32-bit versions of opam"
+synopsis: "DkML component for 32-bit versions of opam"
 description: """
 For 32-bit capable platforms, opam, opam-putenv and opam-installer will be in <share>/staging-files/<platform>.
 But for any platform that does not support 32-bit, this package will install nothing (aka. be a no-op).
@@ -19,8 +19,8 @@ sufficient to be compatible with semver and winget version ordering.
 
 Includes a patch to distinguish MSYS2 from Cygwin, esp. for rsync rather than symlinking which is needed on MSYS2.
 """
-maintainer: ["opensource+diskuv-ocaml@support.diskuv.com"]
-authors: ["Diskuv, Inc. <opensource+diskuv-ocaml@support.diskuv.com>"]
+maintainer: ["opensource+dkml@support.diskuv.com"]
+authors: ["Diskuv, Inc. <opensource+dkml@support.diskuv.com>"]
 license: "Apache-2.0"
 homepage: "https://github.com/diskuv/dkml-component-opam"
 bug-reports: "https://github.com/diskuv/dkml-component-opam/issues"

dkml-component-staging-opam64.opam

@@ -1,7 +1,7 @@
 # This file is generated by dune, edit dune-project instead
 opam-version: "2.0"
 version: "2.2.0~alpha0~20221228-r3"
-synopsis: "DKML component for 64-bit versions of opam"
+synopsis: "DkML component for 64-bit versions of opam"
 description: """
 For 64-bit capable platforms, opam, opam-putenv and opam-installer will be in <share>/staging-files/<platform>.
 But for any platform that does not support 64-bit, this package will install nothing (aka. be a no-op).
@@ -22,8 +22,8 @@ sufficient to be compatible with semver and winget version ordering.
 
 Includes a patch to distinguish MSYS2 from Cygwin, esp. for rsync rather than symlinking which is needed on MSYS2.
 """
-maintainer: ["opensource+diskuv-ocaml@support.diskuv.com"]
-authors: ["Diskuv, Inc. <opensource+diskuv-ocaml@support.diskuv.com>"]
+maintainer: ["opensource+dkml@support.diskuv.com"]
+authors: ["Diskuv, Inc. <opensource+dkml@support.diskuv.com>"]
 license: "Apache-2.0"
 homepage: "https://github.com/diskuv/dkml-component-opam"
 bug-reports: "https://github.com/diskuv/dkml-component-opam/issues"

dune-project

@@ -11,8 +11,10 @@
 ;
 ; 2.2.0~alpha~dev -> 2.2.0-alpha0-20221231
 ; 2.2.0~alpha~1   -> 2.2.0-alpha1-20230601
+; 2.2.0~beta2     -> 2.2.0-beta2-20240409
+; 2.2.0           -> 2.2.0
 ;
-; The dates are commit dates.
+; The dates are commit dates. They should be used until alpha and beta are over.
 ;
 ; The only thing we need to do in the opam version is to use alpha0 instead
 ; of alpha1.
@@ -23,21 +25,21 @@
 (source
  (github diskuv/dkml-component-opam))
 (license Apache-2.0)
-(authors "Diskuv, Inc. <opensource+diskuv-ocaml@support.diskuv.com>")
-(maintainers "opensource+diskuv-ocaml@support.diskuv.com")
+(authors "Diskuv, Inc. <opensource+dkml@support.diskuv.com>")
+(maintainers "opensource+dkml@support.diskuv.com")
 
 (package
  (name dkml-component-common-opam)
- (synopsis "Common code for opam DKML components")
- (description "Common code for opam DKML components")
+ (synopsis "Common code for opam DkML components")
+ (description "Common code for opam DkML components")
  (depends
   (dkml-install                           (>= 0.5.1))
   (cmdliner                               (>= 1.2.0))
   (diskuvbox                              (>= 0.2.0))))
 
 (package
  (name dkml-component-staging-opam32)
- (synopsis "DKML component for 32-bit versions of opam")
+ (synopsis "DkML component for 32-bit versions of opam")
  (description "For 32-bit capable platforms, opam, opam-putenv and opam-installer will be in <share>/staging-files/<platform>.
 But for any platform that does not support 32-bit, this package will install nothing (aka. be a no-op).
 Consumers of the component should place both tools/opam64 and tools/opam32 into the PATH, so that whichever is available can be used.
@@ -69,7 +71,7 @@ Includes a patch to distinguish MSYS2 from Cygwin, esp. for rsync rather than sy
 
 (package
  (name dkml-component-staging-opam64)
- (synopsis "DKML component for 64-bit versions of opam")
+ (synopsis "DkML component for 64-bit versions of opam")
  (description "For 64-bit capable platforms, opam, opam-putenv and opam-installer will be in <share>/staging-files/<platform>.
 But for any platform that does not support 64-bit, this package will install nothing (aka. be a no-op).
 Consumers of the component should place both tools/opam64 and tools/opam32 into the PATH, so that whichever is available can be used.