CMake/Utilities/Release

CMake Release Utilities
***********************

This directory contains scripts used to package CMake itself for distribution
on ``cmake.org``. See also the `CMake Source Code Guide`_.

.. _`CMake Source Code Guide`: ../../Help/dev/source.rst

File Table
----------

The set of package files distributed on ``cmake.org`` varies by CMake version.
Clients providing automatic download functionality may query the set of
package files available using a special file that lists them:

* `File Table v1`_ Documentation

.. _`File Table v1`: files-v1.rst

Docker
------

The ``//`` directories contain Docker specifications that anyone
may use to produce binaries for CMake on the following platforms:

* ``linux/x86_64/``: Linux on ``x86_64`` architectures.
* ``win/x86/``: Windows on ``x86_64`` and ``i386`` architectures.

Each ``//`` directory contains the following:

* ``//base/Dockerfile``:
Produces a base image with a build environment for portable CMake binaries.
This image is published in the `kitware/cmake Docker Hub Repository`_
with tag ``build---base-``.

* ``//deps/Dockerfile``:
Produces an image with custom-built dependencies for portable CMake binaries.
This image is published in the `kitware/cmake Docker Hub Repository`_
with tag ``build---deps-``.

* ``//Dockerfile``:
Produce an image containing a portable CMake binary package.
Build this image using the CMake source directory as the build context.
The resulting image will have an ``/out`` (or ``c:/out``) directory
containing the package. For example, on Linux ``x86_64``:

.. code-block:: console

$ docker build --tag=cmake:build --network none \
-f cmake-src/Utilities/Release/linux/x86_64/Dockerfile cmake-src
$ docker container create --name cmake-build cmake:build
$ docker cp cmake-build:/out .
$ ls out/cmake-*-linux-x86_64.*

On Windows, the ``win/x86`` specifications support both the ``x86_64``
and ``i386`` architectures selected via ``--build-arg ARCH=...``.

* ``//test/Dockerfile``:
Produces a base image with a test environment for packaged CMake binaries.
For example, on Linux ``x86_64``, one may build the test base image:

.. code-block:: console

$ docker build --tag=cmake:test-base \
cmake-src/Utilities/Release/linux/x86_64/test

Then create a local ``test/Dockerfile`` to prepare an image with both the
CMake source tree and the above-built package::

FROM cmake:test-base
COPY cmake-src /opt/cmake/src/cmake
ADD out/cmake--linux-x86_64.tar.gz /opt/
ENV PATH=/opt/cmake--linux-x86_64/bin:$PATH

Build the test image and run it to drive testing:

.. code-block:: console

$ docker build --tag cmake:test --network none -f test/Dockerfile .
$ docker run --network none cmake:test bash test-make.bash
$ docker run --network none cmake:test bash test-ninja.bash

On Windows, the test scripts are called ``test-nmake.bat`` and
``test-ninja.bat``. In the ``x86`` architecture they accept one
argument specifying either ``x86_64`` or ``i386``.

.. _`kitware/cmake Docker Hub Repository`: https://hub.docker.com/r/kitware/cmake

macOS
-----

The ``macos/`` directory contains scripts used to produce dependencies
for building CMake binaries on macOS.