sys/contrib/libsodium/packaging/dotnet-core/README.md

   1 This directory contains scripts and files to package libsodium for .NET Core.
   2
   3 *Note:* The NuGet package is intended for the implementation of language
   4 bindings such as [NSec](https://github.com/ektrah/nsec). It does not provide a
   5 .NET API itself.
   6
   7 In .NET Core, it is customary to provide pre-compiled binaries for all platforms
   8 as NuGet packages. The purpose of the `prepare.py` script in this directory is
   9 to generate a `Makefile` that downloads and builds libsodium binaries for a
  10 number of platforms and assembles them in a NuGet package that can be uploaded
  11 to [nuget.org](https://nuget.org/).
  12
  13 * For Windows, binaries are obtained from
  14   [download.libsodium.org](https://download.libsodium.org/libsodium/releases/).
  15 * For macOS, binaries are extracted from the
  16   [Homebrew libsodium bottle](https://bintray.com/homebrew/bottles/libsodium).
  17 * For Linux, libsodium is compiled in Docker containers.
  18
  19 See `prepare.py` for the complete list of supported platforms.
  20
  21 The metadata for the NuGet package is located in `libsodium.props`.
  22
  23
  24 **Versioning**
  25
  26 Version numbers for the packages for .NET Core consist of three components:
  27
  28 * *libsodium version*
  29   The libsodium version is in the format `X.Y.Z`.
  30 * *package revision*
  31   It may be necessary to release more than one package for a libsodium version,
  32   e.g., when adding support for a new platform or if a release contains a broken
  33   binary. In this case, a package revision number is added as a fourth part to
  34   the libsodium version, starting at `1`. For example, `1.0.16` is the initial
  35   release of the package for libsodium 1.0.16 and `1.0.16.5` is the fifth
  36   revision (sixth release) of that package.
  37 * *pre-release label*
  38   If a package is a pre-release, a label is appended to the version number in
  39   `-preview-##` format where `##` is the number of the pre-release, starting at
  40   `01`. For example, `1.0.16-preview-01` is the first pre-release of the package
  41   for libsodium 1.0.16 and `1.0.16.5-preview-02` the second pre-release of the
  42   fifth revision of the package for libsodium 1.0.16.
  43
  44
  45 **Making a release**
  46
  47 1. Update any existing Docker images.
  48 2. Run `python3 prepare.py <version>` to generate the `Makefile`, where
  49    `<version>` is the package version number in the format described above.
  50 3. Take a look at the generated `Makefile`. It uses `sudo` a few times.
  51 4. Run `make` to download and build the binaries and create the NuGet package.
  52    You may need to install `docker`, `make`, `curl`, `tar` and `unzip` first.
  53 5. Grab a cup of coffee. Downloading the Docker images and compiling the Linux
  54    binaries takes a while. When done, the NuGet package is output as a `.nupkg`
  55    file in the `build` directory.
  56 6. Run `make test` to perform a quick test of the NuGet package. Verify that
  57    everything else in the `.nupkg` file is in place.
  58 7. Publish the release by uploading the `.nupkg` file to
  59    [nuget.org](https://nuget.org/).