2 # This file is part of the GROMACS molecular simulation package.
4 # Copyright (c) 2020,2021, by the GROMACS development team, led by
5 # Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
6 # and including many others, as listed in the AUTHORS file in the
7 # top-level source directory and at http://www.gromacs.org.
9 # GROMACS is free software; you can redistribute it and/or
10 # modify it under the terms of the GNU Lesser General Public License
11 # as published by the Free Software Foundation; either version 2.1
12 # of the License, or (at your option) any later version.
14 # GROMACS is distributed in the hope that it will be useful,
15 # but WITHOUT ANY WARRANTY; without even the implied warranty of
16 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 # Lesser General Public License for more details.
19 # You should have received a copy of the GNU Lesser General Public
20 # License along with GROMACS; if not, see
21 # http://www.gnu.org/licenses, or write to the Free Software Foundation,
22 # Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
24 # If you want to redistribute modifications to GROMACS, please
25 # consider that scientific software is very special. Version
26 # control is crucial - bugs must be traceable. We will be happy to
27 # consider code for inclusion in the official distribution, but
28 # derived work must not be called official GROMACS. Details are found
29 # in the README & COPYING files - if they are missing, get the
30 # official version at http://www.gromacs.org.
32 # To help us fund GROMACS development, we humbly ask that you cite
33 # the research papers on the package. Check out http://www.gromacs.org.
35 """A utility module to help manage the matrix of configurations for CI testing and build containers.
37 When called as a stand alone script, prints a Docker image name based on the
38 command line arguments. The Docker image name is of the form used in the GROMACS
43 $ python3 -m utility --llvm --doxygen
44 gromacs/ci-ubuntu-20.04-llvm-7-docs
49 As a module, provides importable argument parser and docker image name generator.
51 Note that the parser is created with ``add_help=False`` to make it friendly as a
52 parent parser, but this means that you must derive a new parser from it if you
53 want to see the full generated command line help.
58 # utility.parser does not support `-h` or `--help`
59 parser = argparse.ArgumentParser(
60 description='GROMACS CI image creation script',
61 parents=[utility.parser])
62 # ArgumentParser(add_help=True) is default, so parser supports `-h` and `--help`
65 :file:`scripted_gmx_docker_builds.py`
68 * Paul Bauer <paul.bauer.q@gmail.com>
69 * Eric Irrgang <ericirrgang@gmail.com>
70 * Joe Jordan <e.jjordan12@gmail.com>
71 * Mark Abraham <mark.j.abraham@gmail.com>
72 * Gaurav Garg <gaugarg@nvidia.com>
79 parser = argparse.ArgumentParser(description='GROMACS CI image slug options.', add_help=False)
80 """A parent parser for tools referencing image parameters.
82 This argparse parser is defined for convenience and may be used to partially initialize
85 .. warning:: Do not modify this parser.
87 Instead, inherit from it with the *parents* argument to :py:class:`argparse.ArgumentParser`
90 parser.add_argument('--cmake', nargs='*', type=str, default=['3.16.3', '3.17.2', '3.18.4', '3.21.2'], # new minimum required versions
91 help='Selection of CMake version to provide to base image')
93 compiler_group = parser.add_mutually_exclusive_group()
94 compiler_group.add_argument('--gcc', type=int, nargs='?', const=7, default=7,
95 help='Select GNU compiler tool chain. (Default) '
96 'Some checking is implemented to avoid incompatible combinations')
97 compiler_group.add_argument('--llvm', type=str, nargs='?', const='7', default=None,
98 help='Select LLVM compiler tool chain. '
99 'Some checking is implemented to avoid incompatible combinations')
100 # TODO currently the installation merely gets the latest beta version of oneAPI,
101 # not a specific version. GROMACS probably doesn't need to address that until
102 # oneAPI makes an official release. Also, the resulting container is a mix
103 # of packages with different betaXY version numbers, which hopefully works and
104 # is what Intel intends...
105 compiler_group.add_argument('--oneapi', type=str, nargs='?', const="2021.1.1", default=None,
106 help='Select Intel oneAPI package version.')
108 linux_group = parser.add_mutually_exclusive_group()
109 linux_group.add_argument('--ubuntu', type=str, nargs='?', const='20.04', default='20.04',
110 help='Select Ubuntu Linux base image. (default: ubuntu 20.04)')
111 linux_group.add_argument('--centos', type=str, nargs='?', const='7', default=None,
112 help='Select Centos Linux base image.')
114 parser.add_argument('--cuda', type=str, nargs='?', const='11.0', default=None,
115 help='Select a CUDA version for a base Linux image from NVIDIA.')
117 parser.add_argument('--mpi', type=str, nargs='?', const='openmpi', default=None,
118 help='Enable MPI (default disabled) and optionally select distribution (default: openmpi)')
120 parser.add_argument('--tsan', type=str, nargs='?', const='llvm', default=None,
121 help='Build special compiler versions with TSAN OpenMP support')
123 parser.add_argument('--hipsycl', type=str, nargs='?', default=None,
124 help='Select hipSYCL repository tag/commit/branch.')
126 parser.add_argument('--rocm', type=str, nargs='?', const='debian', default=None,
127 help='Select AMD compute engine version.')
129 parser.add_argument('--intel-compute-runtime', type=str, nargs='?', default=None,
130 help='Select Intel Compute Runtime version.')
132 parser.add_argument('--clfft', type=str, nargs='?', const='master', default=None,
133 help='Add external clFFT libraries to the build image')
135 parser.add_argument('--heffte', type=str, nargs='?', default=None,
136 help='Select heffte repository tag/commit/branch.')
138 parser.add_argument('--doxygen', type=str, nargs='?', const='1.8.5', default=None,
139 help='Add doxygen environment for documentation builds. Also adds other requirements needed for final docs images.')
141 # Supported Python versions for maintained branches.
142 _python_versions = ['3.7.7', '3.8.2', '3.9.1']
143 parser.add_argument('--venvs', nargs='*', type=str, default=_python_versions,
144 help='List of Python versions ("major.minor.patch") for which to install venvs. '
145 'Default: {}'.format(' '.join(_python_versions)))
148 def image_name(configuration: argparse.Namespace) -> str:
149 """Generate docker image name.
151 Image names have the form ``ci-<slug>``, where the configuration slug has the form::
153 <distro>-<version>-<compiler>-<major version>[-<gpusdk>-<version>][-<use case>]
155 This function also applies an appropriate Docker image repository prefix.
158 configuration: Docker image configuration as described by the parsed arguments.
162 for distro in ('centos', 'ubuntu'):
163 version = getattr(configuration, distro, None)
164 if version is not None:
165 elements.append(distro + '-' + version)
167 for compiler in ('llvm', 'gcc'):
168 version = getattr(configuration, compiler, None)
169 if version is not None:
170 elements.append(compiler + '-' + str(version).split('.')[0])
172 for gpusdk in ('cuda', 'hipsycl'):
173 version = getattr(configuration, gpusdk, None)
174 if version is not None:
175 elements.append(gpusdk + '-' + version)
176 if configuration.oneapi is not None:
177 elements.append('oneapi-' + configuration.oneapi)
178 if configuration.intel_compute_runtime is not None:
179 elements.append('intel-' + configuration.intel_compute_runtime)
180 if configuration.rocm is not None:
181 if (configuration.rocm != 'debian'):
182 elements.append('rocm-' + configuration.rocm)
184 # Check for special cases
185 # The following attribute keys indicate the image is built for the named
187 cases = {'doxygen': 'docs',
190 value = getattr(configuration, attr, None)
191 if value is not None:
192 elements.append(cases[attr])
193 slug = '-'.join(elements)
194 # we are using the GitLab container registry to store the images
195 # to get around issues with pulling them repeatedly from DockerHub
196 # and running into the image pull limitation there.
197 return 'registry.gitlab.com/gromacs/gromacs/ci-' + slug
200 if __name__ == "__main__":
201 args = argparse.ArgumentParser(parents=[parser]).parse_args()
202 print(image_name(args))