README.rst
1CMake Release Utilities
2***********************
3
4This directory contains scripts used to package CMake itself for distribution
5on ``cmake.org``. See also the `CMake Source Code Guide`_.
6
7.. _`CMake Source Code Guide`: ../../Help/dev/source.rst
8
9File Table
10----------
11
12The set of package files distributed on ``cmake.org`` varies by CMake version.
13Clients providing automatic download functionality may query the set of
14package files available using a special file that lists them:
15
16* `File Table v1`_ Documentation
17
18.. _`File Table v1`: files-v1.rst
19
20Docker
21------
22
23The ``<os>/<arch>/`` directories contain Docker specifications that anyone
24may use to produce binaries for CMake on the following platforms:
25
26* ``linux/x86_64/``: Linux on ``x86_64`` architectures.
27* ``win/x86/``: Windows on ``x86_64`` and ``i386`` architectures.
28
29Each ``<os>/<arch>/`` directory contains the following:
30
31* ``<os>/<arch>/base/Dockerfile``:
32 Produces a base image with a build environment for portable CMake binaries.
33 This image is published in the `kitware/cmake Docker Hub Repository`_
34 with tag ``build-<os>-<arch>-base-<date>``.
35
36* ``<os>/<arch>/deps/Dockerfile``:
37 Produces an image with custom-built dependencies for portable CMake binaries.
38 This image is published in the `kitware/cmake Docker Hub Repository`_
39 with tag ``build-<os>-<arch>-deps-<date>``.
40
41* ``<os>/<arch>/Dockerfile``:
42 Produce an image containing a portable CMake binary package.
43 Build this image using the CMake source directory as the build context.
44 The resulting image will have an ``/out`` (or ``c:/out``) directory
45 containing the package. For example, on Linux ``x86_64``:
46
47 .. code-block:: console
48
49 $ docker build --tag=cmake:build --network none \
50 -f cmake-src/Utilities/Release/linux/x86_64/Dockerfile cmake-src
51 $ docker container create --name cmake-build cmake:build
52 $ docker cp cmake-build:/out .
53 $ ls out/cmake-*-linux-x86_64.*
54
55 On Windows, the ``win/x86`` specifications support both the ``x86_64``
56 and ``i386`` architectures selected via ``--build-arg ARCH=...``.
57
58* ``<os>/<arch>/test/Dockerfile``:
59 Produces a base image with a test environment for packaged CMake binaries.
60 For example, on Linux ``x86_64``, one may build the test base image:
61
62 .. code-block:: console
63
64 $ docker build --tag=cmake:test-base \
65 cmake-src/Utilities/Release/linux/x86_64/test
66
67 Then create a local ``test/Dockerfile`` to prepare an image with both the
68 CMake source tree and the above-built package::
69
70 FROM cmake:test-base
71 COPY cmake-src /opt/cmake/src/cmake
72 ADD out/cmake-<ver>-linux-x86_64.tar.gz /opt/
73 ENV PATH=/opt/cmake-<ver>-linux-x86_64/bin:$PATH
74
75 Build the test image and run it to drive testing:
76
77 .. code-block:: console
78
79 $ docker build --tag cmake:test --network none -f test/Dockerfile .
80 $ docker run --network none cmake:test bash test-make.bash
81 $ docker run --network none cmake:test bash test-ninja.bash
82
83 On Windows, the test scripts are called ``test-nmake.bat`` and
84 ``test-ninja.bat``. In the ``x86`` architecture they accept one
85 argument specifying either ``x86_64`` or ``i386``.
86
87.. _`kitware/cmake Docker Hub Repository`: https://hub.docker.com/r/kitware/cmake
88
89macOS
90-----
91
92The ``macos/`` directory contains scripts used to produce dependencies
93for building CMake binaries on macOS.
94