diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 439e2302a..25a891ead 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -42,7 +42,6 @@ jobs:
- os: ubuntu-latest
python-version: "3.9"
conda-standalone: conda-standalone
- check-docs: true
- os: ubuntu-latest
python-version: "3.10"
conda-standalone: conda-standalone-nightly
@@ -52,6 +51,7 @@ jobs:
- os: ubuntu-latest
python-version: "3.12"
conda-standalone: conda-standalone
+ check-docs-schema: true
# MACOS
- os: macos-13
python-version: "3.9"
@@ -156,10 +156,11 @@ jobs:
with:
token: ${{ secrets.CODECOV_TOKEN }}
flags: integration
- - name: Check docs are up-to-date
- if: matrix.check-docs
+ - name: Check docs and schema are up-to-date
+ if: matrix.check-docs-schema
run: |
python scripts/make_docs.py
+ python constructor/_schema.py
git diff --exit-code
- name: Upload the example installers as artifacts
if: github.event_name == 'pull_request' && matrix.python-version == '3.9'
diff --git a/CONSTRUCT.md b/CONSTRUCT.md
index 27d449eb9..adbcc0bac 100644
--- a/CONSTRUCT.md
+++ b/CONSTRUCT.md
@@ -34,29 +34,30 @@ are not available here.
> Note: This content is also available in the CLI as `constructor --help-construct`
## Available keys
-### `name`
-_required:_ yes
-_type:_ string
+> This is only a name and description render of the `constructor` JSON Schema.
+> For more details, consider using an online viewer like
+> [json-schema.app](https://json-schema.app/view/%23?url=https%3A%2F%2Fraw.githubusercontent.com%2Fconda%2Fconstructor%2Frefs%2Fheads%2Fmain%2Fconstructor%2Fdata%2Fconstruct.schema.json)
+
+
+### `$schema`
+
+JSON Schema URL or path used to validate this input file.
+
+### `name`
Name of the installer. Names may be composed of letters, numbers,
-underscores, dashes, and periods, but may not begin or end with a
+underscores, dashes, and periods, but must not begin or end with a
dash or period.
### `version`
-_required:_ yes
-_type:_ string
-
Version of the installer. Versions may be composed of letters, numbers,
-underscores, dashes, and periods, but may not begin or end with a
+underscores, dashes, and periods, but must not begin or end with a
dash or period.
### `channels`
-_required:_ no
-_type:_ list
-
The conda channels from which packages are retrieved. At least one channel must
be supplied, either in `channels` or `channels_remap`.
@@ -64,9 +65,6 @@ See notes in `channels_remap` for details about local channels.
### `channels_remap`
-_required:_ no
-_type:_ list
-
A list of `src/dest` channel URL pairs. When building the installer, conda will
use the `src` channels to solve and fetch the packages. However, the resulting
installation will see the packages as coming from the `dest` equivalent.
@@ -78,20 +76,17 @@ channels_remap:
- src: file:///tmp/a3/conda-bld # [unix]
dest: https://repo.anaconda.com/pkgs/main # [unix]
- src: file:///D:/tmp/a3/conda-bld # [win]
- dest: https://repo.anaconda.com/pkgs/main # [unix]
+ dest: https://repo.anaconda.com/pkgs/main # [win]
```
At least one channel must be supplied, either in `channels` or `channels_remap`.
### `specs`
-_required:_ no
-_types:_ list, string
-
A list of package specifications; e.g. `python 2.7*`, `pyzmq` or `numpy >=1.8`.
The specifications are identical in form and purpose to those that would be
included in a `conda create --file` command. Packages may also be specified
-by an exact URL; e.g.,
+by an exact URL, e.g.,
`https://repo.anaconda.com/pkgs/main/osx-64/openssl-1.0.2o-h26aff7b_0.tar.bz2`.
This key can also take a `str` pointing to a requirements file with the same syntax.
@@ -103,21 +98,15 @@ configured solver plugin is also installed in that environment.
### `user_requested_specs`
-_required:_ no
-_types:_ list, string
-
A list of package specifications to be recorded as "user-requested" for the
initial environment in conda's history file. This information is used by newer
versions of conda to better filter its package choices on subsequent installs;
for example, if `python=3.6` is included, then conda will always seek versions
-of packages compatible with Python 3.6. If this is option is not provided, it
+of packages compatible with Python 3.6. If this option is not provided, it
will be set equal to the value of `specs`.
### `virtual_specs`
-_required:_ no
-_type:_ list
-
A list of virtual packages that must be satisfied at install time. Virtual
packages must start with `__`. For example, `__osx>=11` or `__glibc>=2.24`.
These specs are dry-run solved offline by the bundled `--conda-exe` binary.
@@ -129,20 +118,14 @@ involved as long as only `>=`, `<` or `,` are used.
### `exclude`
-_required:_ no
-_type:_ list
-
A list of package names to be excluded after the `specs` have been resolved.
For example, you can say that `readline` should be excluded, even though it
is contained as a result of resolving the specs for `python 2.7`.
### `menu_packages`
-_required:_ no
-_type:_ list
-
A list of packages with menu items to be installed. The packages must have
-necessary metadata in `Menu/.json`). By default, all menu items
+necessary metadata in `Menu/.json`. By default, all menu items
found in the installation will be created; supplying this list allows a
subset to be selected instead. If an empty list is supplied, no shortcuts will
be created.
@@ -155,16 +138,10 @@ the `--conda-exe` binary. The only accepted value is an empty list (`[]`).
### `ignore_duplicate_files`
-_required:_ no
-_type:_ boolean
-
By default, constructor will warn you when adding packages with duplicate
files in them. Setting this option to false will raise an error instead.
-### `install_in_dependency_order`
-
-_required:_ no
-_types:_ boolean, string
+### ~~`install_in_dependency_order`~~
_Obsolete_. The current version of constructor relies on the standalone
conda executable for its installation behavior. This option is now
@@ -172,9 +149,6 @@ ignored with a warning.
### `environment`
-_required:_ no
-_type:_ string
-
Name of the environment to construct from. If this option is present, the
`specs` argument will be ignored. Using this option allows the user to
curate the enviromment interactively using standard `conda` commands, and
@@ -183,33 +157,23 @@ reproduced.
### `environment_file`
-_required:_ no
-_type:_ string
-
Path to an environment file (TXT or YAML) to construct from. If this option
is present, the `specs` argument will be ignored. Instead, constructor will
-call conda to create a temporary environment, constructor will build and
+call conda to create a temporary environment, constructor will build an
installer from that, and the temporary environment will be removed.
This ensures that constructor is using the precise local conda configuration
to discover and install the packages. The created environment MUST include
`python`.
-Read notes about the solver in the `specs` field.
+See notes about the solver in the `specs` field for more information.
### `transmute_file_type`
-_required:_ no
-_type:_ string
-
-File type extension for the files to be transmuted into. Currently supports
-only '.conda'. See conda-package-handling for supported extension names.
+File type extension for the files to be transmuted into.
If left empty, no transmuting is done.
### `conda_default_channels`
-_required:_ no
-_type:_ list
-
If this value is provided as well as `write_condarc`, then the channels
in this list will be included as the value of the `default_channels:`
option in the environment's `.condarc` file. This will have an impact
@@ -217,32 +181,13 @@ only if `conda` is included in the environmnent.
### `conda_channel_alias`
-_required:_ no
-_type:_ string
-
The channel alias that would be assumed for the created installer
-(only useful if it includes conda).
+(only useful if it includes `conda`).
### `extra_envs`
-_required:_ no
-_type:_ dictionary
-
Create more environments in addition to the default `base` provided by `specs`,
-`environment` or `environment_file`. This should be a map of `str` (environment
-name) to a dictionary of options:
-- `specs` (list of str): which packages to install in that environment
-- `environment` (str): same as global option, for this env
-- `environment_file` (str): same as global option, for this env
-- `channels` (list of str): using these channels; if not provided, the global
- value is used. To override inheritance, set it to an empty list.
-- `channels_remap` (list of str): same as global option, for this env;
- if not provided, the global value is used. To override inheritance, set it to
- an empty list.
-- `user_requested_specs` (list of str): same as the global option, but for this env;
- if not provided, global value is _not_ used
-- `menu_packages` (list of str): same as the global option, for this env;
- if not provided, the global value is _not_ used.
+`environment` or `environment_file`.
Notes:
- `ignore_duplicate_files` will always be considered `True` if `extra_envs` is in use.
@@ -255,27 +200,18 @@ Notes:
### `register_envs`
-_required:_ no
-_type:_ boolean
-
Whether to register the environments created by the installer (both `base` and `extra_envs`)
-in `~/.conda/environments.txt`. Only compatible with conda-standalone >=23.9. Defaults to `True`.
+in `~/.conda/environments.txt`. Only compatible with conda-standalone >=23.9.
### `installer_filename`
-_required:_ no
-_type:_ string
-
The filename of the installer being created. If not supplied, a reasonable
-default will determined by the `name`, `version`, platform, and installer type.
+default will be determined by the `name`, `version`, `platform`, and `installer_type`.
### `installer_type`
-_required:_ no
-_types:_ string, list
-
-The type of the installer being created. Possible values are:
-- `sh`: shell-based installer for Linux or macOS;
+The type of the installer being created. Possible values are:
+- `sh`: shell-based installer for Linux or macOS
- `pkg`: macOS GUI installer built with Apple's `pkgbuild`
- `exe`: Windows GUI installer built with NSIS
@@ -283,51 +219,28 @@ The default type is `sh` on Linux and macOS, and `exe` on Windows. A special
value of `all` builds _both_ `sh` and `pkg` installers on macOS, as well
as `sh` on Linux and `exe` on Windows.
-Notes for silent mode `/S` on Windows EXEs:
-- NSIS Silent mode will not print any error message, but will silently abort the installation.
- If needed, [NSIS log-builds][nsis-log] can be used to print to `%PREFIX%\install.log`, which
- can be searched for `::error::` strings. Pre- and post- install scripts will only throw an error
- if the environment variable `NSIS_SCRIPTS_RAISE_ERRORS` is set.
-- The `/D` flag can be used to specify the target location. It must be the last argument in
- the command and should NEVER be quoted, even if it contains spaces. For example:
- `CMD.EXE /C START /WAIT myproject.exe /S /D=C:\path with spaces\my project`.
-
-[nsis-log]: https://nsis.sourceforge.io/Special_Builds
-
### `license_file`
-_required:_ no
-_type:_ string
-
Path to the license file being displayed by the installer during the install
-process. It must be plain text (.txt) for shell-based installers. On PKG,
+process. It must be plain text (.txt) for shell-based installers. For PKG,
.txt, .rtf and .html are supported. On Windows, .txt and .rtf are supported.
### `keep_pkgs`
-_required:_ no
-_type:_ boolean
-
-If `False` (default), the package cache in the `pkgs` subdirectory is removed
+If `False`, the package cache in the `pkgs` subdirectory is removed
when the installation process is complete. If `True`, this subdirectory and
-its contents are preserved. If `keep_pkgs` is `False`, Unix `.sh` and Windows `.msi`
+its contents are preserved. If `keep_pkgs` is `False`, Unix `.sh` and Windows `.exe`
installers offer a command-line option (`-k` and `/KeepPkgCache`, respectively)
to preserve the package cache.
### `batch_mode`
-_required:_ no
-_type:_ boolean
-
-Only affects ``.sh`` installers. If ``False`` (default), the installer launches
+Only affects `.sh` installers. If `False`, the installer launches
an interactive wizard guiding the user through the available options. If
-``True``, the installer runs automatically as if ``-b`` was passed.
+`True`, the installer runs automatically as if `-b` was passed.
### `signing_identity_name`
-_required:_ no
-_type:_ string
-
By default, the MacOS pkg installer isn't signed. If an identity name is specified
using this option, it will be used to sign the installer with Apple's `productsign`.
Note that you will need to have a certificate (usually an "Installer certificate")
@@ -337,9 +250,6 @@ accessible keychains. Common values for this option follow this format
### `notarization_identity_name`
-_required:_ no
-_type:_ string
-
If the pkg installer is going to be signed with `signing_identity_name`, you
can also prepare the bundle for notarization. This will use Apple's `codesign`
to sign `conda.exe`. For this, you need an "Application certificate" (different from the
@@ -348,9 +258,6 @@ to sign `conda.exe`. For this, you need an "Application certificate" (different
### `windows_signing_tool`
-_required:_ no
-_type:_ string
-
The tool used to sign Windows installers. Must be one of: azuresigntool, signtool.
Some tools require `signing_certificate` to be set.
Defaults to `signtool` if `signing_certificate` is set.
@@ -360,16 +267,10 @@ https://conda.github.io/constructor/howto/#signing-exe-installers
### `signing_certificate`
-_required:_ no
-_type:_ string
-
On Windows only, set this key to the path of the certificate file to be used
with the `windows_signing_tool`.
-### `attempt_hardlinks`
-
-_required:_ no
-_types:_ boolean, string
+### ~~`attempt_hardlinks`~~
_Obsolete_. The current version of constructor relies on the standalone
conda executable for its installation behavior. This option is now
@@ -377,17 +278,11 @@ ignored with a warning.
### `write_condarc`
-_required:_ no
-_type:_ boolean
-
By default, no `.condarc` file is written. If set, a `.condarc` file is written to
-the base environment if there are any channels or conda_default_channels is set.
+the installation directory if there are any channels or `conda_default_channels` is set.
### `condarc`
-_required:_ no
-_types:_ dictionary, string
-
If set, a `.condarc` file is written to the base environment containing the contents
of this value. The value can either be a string (likely a multi-line string) or
a dictionary, which will be converted to a YAML string for writing. _Note:_ if this
@@ -396,33 +291,21 @@ file (`write_condarc`, `conda_default_channels`, etc.) are ignored.
### `company`
-_required:_ no
-_type:_ string
-
-Name of the company/entity who is responsible for the installer.
+Name of the company/entity responsible for the installer.
### `reverse_domain_identifier`
-_required:_ no
-_type:_ string
-
Unique identifier for this package, formatted with reverse domain notation. This is
used internally in the PKG installers to handle future updates and others. If not
provided, it will default to `io.continuum`. (MacOS only)
### `uninstall_name`
-_required:_ no
-_type:_ string
-
Application name in the Windows "Programs and Features" control panel.
Defaults to `${NAME} ${VERSION} (Python ${PYVERSION} ${ARCH})`.
### `script_env_variables`
-_required:_ no
-_type:_ dictionary
-
Dictionary of additional environment variables to be made available to
the pre_install and post_install scripts, in the form of VAR:VALUE
pairs. These environment variables are in addition to those in the
@@ -444,9 +327,6 @@ comments for all platforms.
### `pre_install`
-_required:_ no
-_type:_ string
-
Path to a pre-install script, run after the package cache has been set, but
before the files are linked to their final locations. As a result, you should
only rely on tools known to be available on most systems (e.g. `bash`, `cmd`,
@@ -454,12 +334,9 @@ etc). See `post_install` for information about available environment variables.
### `pre_install_desc`
-_required:_ no
-_type:_ string
-
A description of the purpose of the supplied `pre_install` script. If this
string is supplied and non-empty, then the Windows and macOS GUI installers
-will display it along with checkbox to enable or disable the execution of the
+will display it along with a checkbox to enable or disable the execution of the
script. If this string is not supplied, it is assumed that the script
is compulsory and the option to disable it will not be offered.
@@ -467,9 +344,6 @@ This option has no effect on `SH` installers.
### `post_install`
-_required:_ no
-_type:_ string
-
Path to a post-install script. Some notes:
- For Unix `.sh` installers, the shebang line is respected if present;
@@ -491,17 +365,14 @@ Path to a post-install script. Some notes:
If necessary, you can activate the installed `base` environment like this:
-- Unix: `source "$PREFIX/etc/profile.d/conda.sh" && conda activate "$PREFIX"`
+- Unix: `. "$PREFIX/etc/profile.d/conda.sh" && conda activate "$PREFIX"`
- Windows: `call "%PREFIX%\Scripts\activate.bat"`
### `post_install_desc`
-_required:_ no
-_type:_ string
-
A description of the purpose of the supplied `post_install` script. If this
string is supplied and non-empty, then the Windows and macOS GUI installers
-will display it along with checkbox to enable or disable the execution of the
+will display it along with a checkbox to enable or disable the execution of the
script. If this string is not supplied, it is assumed that the script
is compulsory and the option to disable it will not be offered.
@@ -509,10 +380,7 @@ This option has no effect on `SH` installers.
### `pre_uninstall`
-_required:_ no
-_type:_ string
-
-Path to a pre uninstall script. This is only supported for on Windows,
+Path to a pre uninstall script. This is only supported on Windows,
and must be a `.bat` file. Installation path is available as `%PREFIX%`.
Metadata about the installer can be found in the `%INSTALLER_NAME%`,
`%INSTALLER_VER%`, `%INSTALLER_PLAT%` environment variables.
@@ -520,42 +388,29 @@ Metadata about the installer can be found in the `%INSTALLER_NAME%`,
### `default_prefix`
-_required:_ no
-_type:_ string
-
Set default install prefix. On Linux, if not provided, the default prefix
is `${HOME}/` (or, if `HOME` is not set, `/opt/`). On Windows,
-this is used only for "Just Me" installation; for "All Users" installation,
+this is used only for "Just Me" installations; for "All Users" installations,
use the `default_prefix_all_users` key. If not provided, the default prefix
is `%USERPROFILE%\`. Environment variables will be expanded at
-installation time.
+install time.
### `default_prefix_domain_user`
-_required:_ no
-_type:_ string
-
-Set default installation prefix for domain user. If not provided, the
-installation prefix for domain user will be `%LOCALAPPDATA%\`.
+Set default installation prefix for domain users. If not provided, the
+installation prefix for domain users will be `%LOCALAPPDATA%\`.
By default, it is different from the `default_prefix` value to avoid installing
-the distribution in the roaming profile. Environment variables will be expanded
-at installation time. Windows only.
+the distribution into the roaming profile. Environment variables will be expanded
+at install time. Windows only.
### `default_prefix_all_users`
-_required:_ no
-_type:_ string
-
-Set default installation prefix for All Users installation. If not provided,
-the installation prefix for all users installation will be
-`%ALLUSERSPROFILE%\`. Environment variables will be expanded at installation
-time. Windows only.
+Set default installation prefix for All Users installations. If not provided,
+the installation prefix will be `%ALLUSERSPROFILE%\`.
+Environment variables will be expanded at install time. Windows only.
### `default_location_pkg`
-_required:_ no
-_type:_ string
-
Default installation subdirectory in the chosen volume. In PKG installers,
default installation locations are configured differently. The user can choose
between a "Just me" installation (which would result in `~/`) or another
@@ -569,9 +424,6 @@ macOS only.
### `pkg_domains`
-_required:_ no
-_type:_ dictionary
-
The domains the package can be installed into. For a detailed explanation, see:
https://developer.apple.com/library/archive/documentation/DeveloperTools/Reference/DistributionDefinitionRef/Chapters/Distribution_XML_Ref.html
constructor defaults to `enable_anywhere=true` and `enable_currentUserHome=true`.
@@ -580,32 +432,23 @@ macOS only.
### `pkg_name`
-_required:_ no
-_type:_ string
-
Internal identifier for the installer. This is used in the build prefix and will
determine part of the default location path. Combine with `default_location_pkg`
-for more flexibility. If not provided, the value of `name` will be used. (MacOS only)
+for more flexibility. If not provided, the value of `name` will be used. (macOS only)
### `install_path_exists_error_text`
-_required:_ no
-_type:_ string
-
Error message that will be shown if the installation path already exists.
You cannot use double quotes or newlines. The placeholder `{CHOSEN_PATH}` is
available and set to the destination causing the error. Defaults to:
> '{CHOSEN_PATH}' already exists. Please, relaunch the installer and
-> choose another location in the Destination Select step.
+choose another location in the Destination Select step.
-(MacOS only)
+(PKG only)
### `progress_notifications`
-_required:_ no
-_type:_ boolean
-
Whether to show UI notifications on PKG installers. On large installations,
the progress bar reaches ~90% very quickly and stays there for a long time.
This might look like the installer froze. This option enables UI notifications
@@ -614,179 +457,117 @@ so the user receives updates after each command executed by the installer.
### `welcome_image`
-_required:_ no
-_type:_ string
-
Path to an image in any common image format (`.png`, `.jpg`, `.tif`, etc.)
to be used as the welcome image for the Windows and PKG installers.
-The image is re-sized to 164 x 314 pixels on Windows and 1227 x 600 on Macos.
-By default, an image is automatically generated on Windows. On MacOS, Anaconda's
+The image is re-sized to 164 x 314 pixels on Windows and 1227 x 600 on macOS.
+By default, an image is automatically generated on Windows. On macOS, Anaconda's
logo is shown if this key is not provided. If you don't want a background on
PKG installers, set this key to `""` (empty string).
### `header_image`
-_required:_ no
-_type:_ string
-
Like `welcome_image` for Windows, re-sized to 150 x 57 pixels.
### `icon_image`
-_required:_ no
-_type:_ string
-
Like `welcome_image` for Windows, re-sized to 256 x 256 pixels.
### `default_image_color`
-_required:_ no
-_type:_ string
-
The color of the default images (when not providing explicit image files)
-used on Windows. Possible values are `red`, `green`, `blue`, `yellow`.
-The default is `blue`.
+used on Windows.
### `welcome_image_text`
-_required:_ no
-_type:_ string
-
If `welcome_image` is not provided, use this text when generating the image
(Windows and PKG only). Defaults to `name` on Windows.
### `header_image_text`
-_required:_ no
-_type:_ string
-
If `header_image` is not provided, use this text when generating the image
(Windows only). Defaults to `name`.
### `initialize_conda`
-_required:_ no
-_type:_ boolean
-
Add an option to the installer so the user can choose whether to run `conda init`
-after the install. See also `initialize_by_default`.
+after the installation (Unix), or to add certain subdirectories of the installation
+to PATH (Windows). See also `initialize_by_default`.
### `initialize_by_default`
-_required:_ no
-_type:_ boolean
-
-Whether to add the installation to the PATH environment variable. The default
-is true for GUI installers (msi, pkg) and False for shell installers. The user
+Default value for the option added by `initialize_conda`. The default
+is true for GUI installers (EXE, PKG) and false for shell installers. The user
is able to change the default during interactive installation. NOTE: For Windows,
`AddToPath` is disabled when `InstallationType=AllUsers`.
-### `register_python`
+Only applies if `initialize_conda` is true.
-_required:_ no
-_type:_ boolean
+### `register_python`
Whether to offer the user an option to register the installed Python instance as the
system's default Python. (Windows only)
### `register_python_default`
-_required:_ no
-_type:_ boolean
-
Default choice for whether to register the installed Python instance as the
system's default Python. The user is still able to change this during
interactive installation. (Windows only).
-### `check_path_length`
+Only applies if `register_python` is true.
-_required:_ no
-_type:_ boolean
+### `check_path_length`
Check the length of the path where the distribution is installed to ensure nodejs
-can be installed. Raise a message to request shorter path (less than 46 character)
-or enable long path on windows > 10 (require admin right). Default is True. (Windows only).
-
-Read notes about the particularities of Windows silent mode `/S` in the
-`installer_type` documentation.
+can be installed. Raise a message to request shorter paths (less than 46 character)
+or enable long paths on windows > 10 (require admin right). Default is True. (Windows only).
### `check_path_spaces`
-_required:_ no
-_type:_ boolean
-
-Check if the path where the distribution is installed contains spaces. Default is True.
+Check if the path where the distribution is installed contains spaces.
To allow installations with spaces, change to False. Note that:
- A recent conda-standalone (>=22.11.1) or equivalent is needed for full support.
- `conda` cannot be present in the `base` environment
-Read notes about the particularities of Windows silent mode `/S` in the
-`installer_type` documentation.
-
### `nsis_template`
-_required:_ no
-_type:_ string
-
-If `nsis_template` is not provided, constructor uses its default
-NSIS template. For more complete customization for the installation experience,
-provide an NSIS template file. (Windows only).
+Path to an NSIS template file to use instead of the default template. (Windows only)
### `welcome_file`
-_required:_ no
-_type:_ string
-
-If `installer_type` is `pkg` on MacOS, this message will be
+If `installer_type` is `pkg` on macOS, this message will be
shown before the license information, right after the introduction.
File can be plain text (.txt), rich text (.rtf) or HTML (.html). If
both `welcome_file` and `welcome_text` are provided, `welcome_file` takes precedence.
-(MacOS only).
-If the installer is for windows and welcome file type is nsi,
+If the installer is for Windows and the welcome file type is nsi,
it will use the nsi script to add in extra pages before the installer
begins the installation process.
### `welcome_text`
-_required:_ no
-_type:_ string
-
-If `installer_type` is `pkg` on MacOS, this message will be
+If `installer_type` is `pkg` on macOS, this message will be
shown before the license information, right after the introduction.
If this key is missing, it defaults to a message about Anaconda Cloud.
You can disable it altogether so it defaults to the system message
if you set this key to `""` (empty string).
-(MacOS only).
### `readme_file`
-_required:_ no
-_type:_ string
-
-If `installer_type` is `pkg` on MacOS, this message will be
+If `installer_type` is `pkg` on macOS, this message will be
shown before the license information, right after the welcome screen.
File can be plain text (.txt), rich text (.rtf) or HTML (.html). If
both `readme_file` and `readme_text` are provided, `readme_file` takes precedence.
-(MacOS only).
### `readme_text`
-_required:_ no
-_type:_ string
-
-If `installer_type` is `pkg` on MacOS, this message will be
+If `installer_type` is `pkg` on macOS, this message will be
shown before the license information, right after the welcome screen.
If this key is missing, it defaults to a message about Anaconda Cloud.
You can disable it altogether if you set this key to `""` (empty string).
-(MacOS only).
### `post_install_pages`
-_required:_ no
-_types:_ list, string
-
Adds extra pages to the installers to be shown after installation.
For PKG installers, these can be compiled `installer` plug-ins or
@@ -798,35 +579,25 @@ They will be inserted as-is before the conclusion page.
### `conclusion_file`
-_required:_ no
-_type:_ string
-
-If `installer_type` is `pkg` on MacOS, this message will be
+If `installer_type` is `pkg` on macOS, this message will be
shown at the end of the installer upon success. File can be
plain text (.txt), rich text (.rtf) or HTML (.html). If both
`conclusion_file` and `conclusion_text` are provided,
-`conclusion_file` takes precedence. (MacOS only).
+`conclusion_file` takes precedence.
If the installer is for Windows, the file type must be nsi.
### `conclusion_text`
-_required:_ no
-_type:_ string
-
A message that will be shown at the end of the installer upon success.
The behaviour is slightly different across installer types:
- PKG: If this key is missing, it defaults to a message about Anaconda Cloud.
You can disable it altogether so it defaults to the system message if you set this
key to `""` (empty string).
- EXE: The first line will be used as a title. The following lines will be used as text.
-(macOS PKG and Windows only).
### `extra_files`
-_required:_ no
-_type:_ list
-
Extra, non-packaged files that should be added to the installer. If provided as relative
paths, they will be considered relative to the directory where `construct.yaml` is.
This setting can be passed as a list of:
@@ -835,47 +606,24 @@ This setting can be passed as a list of:
### `temp_extra_files`
-_required:_ no
-_type:_ list
-
Temporary files that could be referenced in the installation process (i.e. customized
-`welcome_file` and `conclusion_file` (see above)) . Should be a list of
+`welcome_file` and `conclusion_file`). Should be a list of
file paths, relative to the directory where `construct.yaml` is. In Windows, these
files will be copied into a temporary folder, the NSIS `$PLUGINSDIR`, during
-install process (Windows only).
+the install process (Windows only).
Supports the same values as `extra_files`.
### `build_outputs`
-_required:_ no
-_type:_ list
-
Additional artifacts to be produced after building the installer.
-It expects either a list of strings or single-key dictionaries:
-Allowed keys are:
-- `hash`: The hash of the installer files. The output file is designed to work with the `shasum`
- command and thus has POSIX line endings, including on Windows. Options:
- - `algorithm` (str or list): The hash algorithm. Must be among `hashlib`'s available algorithms:
- https://docs.python.org/3/library/hashlib.html#hashlib.algorithms_available
-- `info.json`: The internal `info` object, serialized to JSON. Takes no options.
-- `pkgs_list`: The list of packages contained in a given environment. Options:
- - `env` (optional, default=`base`): Name of an environment in `extra_envs` to export.
-- `lockfile`: An `@EXPLICIT` lockfile for a given environment. Options:
- - `env` (optional, default=`base`): Name of an environment in `extra_envs` to export.
-- `licenses`: Generate a JSON file with the licensing details of all included packages. Options:
- - `include_text` (optional bool, default=`False`): Whether to dump the license text in the JSON.
- If false, only the path will be included.
- - `text_errors` (optional str, default=`None`): How to handle decoding errors when reading the
- license text. Only relevant if include_text is True. Any str accepted by open()'s 'errors'
- argument is valid. See https://docs.python.org/3/library/functions.html#open.
+It expects either a list of strings or single-key dictionaries.
-### `uninstall_with_conda_exe`
+Allowed strings / keys: `hash`, `info.json`, `licenses`, `lockfile`, `pkgs_list`.
-_required:_ no
-_type:_ boolean
+### `uninstall_with_conda_exe`
-Use the standalone binary to perform the uninstallation.
+Use the standalone binary to perform the uninstallation on Windows.
Requires conda-standalone 24.11.0 or newer.
@@ -897,7 +645,8 @@ Requires conda-standalone 24.11.0 or newer.
- `x86_64`
## Available Platforms
-Specify which platform (`CONDA_SUBDIR`) to build for via the `--platform` argument. If provided, this argument must be formated as `-`, e.g.:
+Specify which platform (`CONDA_SUBDIR`) to build for via the `--platform` argument.
+If provided, this argument must be formated as `-`, e.g.:
- `linux-64`
- `linux-aarch64`
- `linux-ppc64le`
diff --git a/constructor/_schema.py b/constructor/_schema.py
new file mode 100644
index 000000000..c249c8181
--- /dev/null
+++ b/constructor/_schema.py
@@ -0,0 +1,844 @@
+# (c) 2016 Anaconda, Inc. / https://anaconda.com
+# All Rights Reserved
+#
+# constructor is distributed under the terms of the BSD 3-clause license.
+# Consult LICENSE.txt or http://opensource.org/licenses/BSD-3-Clause.
+"""
+Logic to generate the JSON Schema for construct.yaml, using Pydantic.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from enum import StrEnum
+from hashlib import algorithms_guaranteed
+from inspect import cleandoc
+from pathlib import Path
+from typing import Annotated, Literal, TypeAlias, Union # noqa
+
+from pydantic import BaseModel, ConfigDict, Field
+
+HERE = Path(__file__).parent
+SCHEMA_PATH = HERE / "data" / "construct.schema.json"
+NAME_REGEX = VERSION_REGEX = r"^[a-zA-Z0-9_]([a-zA-Z0-9._-]*[a-zA-Z0-9_])?$"
+ENV_NAME_REGEX = r"^[^/:# ]+$"
+NonEmptyStr = Annotated[str, Field(min_length=1)]
+_base_config_dict = ConfigDict(
+ extra="forbid",
+ use_attribute_docstrings=True,
+)
+
+
+class WinSignTools(StrEnum):
+ AZURESIGNTOOL = "azuresigntool"
+ AZURESIGNTOOL_EXE = "azuresigntool.exe"
+ SIGNTOOL = "signtool"
+ SIGNTOOL_EXE = "signtool.exe"
+
+
+class InstallerTypes(StrEnum):
+ ALL = "all"
+ EXE = "exe"
+ PKG = "pkg"
+ SH = "sh"
+
+
+class PkgDomains(StrEnum):
+ ANYWHERE = "enable_anywhere"
+ CURRENT_USER_HOME = "enable_currentUserHome"
+ LOCAL_SYSTEM = "enable_localSystem"
+
+
+class ChannelRemap(BaseModel):
+ model_config: ConfigDict = _base_config_dict
+
+ src: NonEmptyStr = ...
+ "Source channel, before being mapped"
+ dest: NonEmptyStr = ...
+ "Target channel, after being mapped"
+
+
+class ExtraEnv(BaseModel):
+ model_config: ConfigDict = _base_config_dict
+
+ specs: list[NonEmptyStr] = []
+ "Which packages to install in this environment"
+ environment: NonEmptyStr | None = None
+ "Same as global option, for this environment"
+ environment_file: NonEmptyStr | None = None
+ "Same as global option, for this environment"
+ channels: list[NonEmptyStr] | None = None
+ """
+ Solve specs using these channels; if not provided, the global
+ value is used. To override inheritance, set it to an empty list.
+ """
+ channels_remap: list[ChannelRemap] | None = None
+ """
+ Same as global option, for this env; if not provided, the global
+ value is used. To override inheritance, set it to an empty list.
+ """
+ user_requested_specs: list[NonEmptyStr] | None = None
+ """
+ Same as the global option, but for this env.
+ If not provided, global value is _not_ used.
+ """
+ menu_packages: list[NonEmptyStr] | None = None
+ """
+ Same as the global option, but for this env.
+ If not provided, global value is _not_ used.
+ """
+ exclude: list[NonEmptyStr] | None = None
+ """
+ Same as the global option, but for this env.
+ See global option for notes about overrides.
+ """
+
+
+class BuildOutputs(StrEnum):
+ "Allowed keys in 'build_outputs' setting."
+
+ HASH = "hash"
+ INFO_JSON = "info.json"
+ LICENSES = "licenses"
+ LOCKFILE = "lockfile"
+ PKGS_LIST = "pkgs_list"
+
+
+_GuaranteedAlgorithmsEnum = StrEnum(
+ "GuaranteedAlgorithmsEnum",
+ tuple(sorted((value, value) for value in algorithms_guaranteed)),
+)
+
+
+class _HashBuildOutputOptions(BaseModel):
+ model_config: ConfigDict = _base_config_dict
+ algorithm: _GuaranteedAlgorithmsEnum | list[_GuaranteedAlgorithmsEnum]
+ "The hash algorithm. Must be one of `hashlib.algorithms_guaranteed`."
+
+
+class _InfoJsonBuildOutputOptions(BaseModel):
+ model_config: ConfigDict = _base_config_dict
+
+
+class _PkgsListBuildOutputOptions(BaseModel):
+ model_config: ConfigDict = _base_config_dict
+ env: NonEmptyStr = "base"
+ "Name of an environment in 'extra_envs' to be exported."
+
+
+class _LockfileBuildOutputOptions(BaseModel):
+ model_config: ConfigDict = _base_config_dict
+ env: NonEmptyStr = "base"
+ "Name of an environment in 'extra_envs' to be exported."
+
+
+class _LicensesBuildOutputOptions(BaseModel):
+ model_config: ConfigDict = _base_config_dict
+ include_text: bool = False
+ "Whether to dump the license text in the JSON. If false, only the path will be included."
+ text_errors: str | None = None
+ """
+ How to handle decoding errors when reading the license text. Only relevant if `include_text` is
+ True. Any str accepted by `open()`'s 'errors' argument is valid. See
+ https://docs.python.org/3/library/functions.html#open.
+ """
+
+
+class HashBuildOutput(BaseModel):
+ """
+ The hash of the installer files. The output file is designed to work with the `shasum`
+ command and thus has POSIX line endings, including on Windows
+ """
+
+ model_config: ConfigDict = _base_config_dict
+ hash_: _HashBuildOutputOptions
+
+
+class InfoJsonBuildOutput(BaseModel):
+ "The internal `info` object, serialized to JSON. Takes no options."
+
+ model_config: ConfigDict = _base_config_dict
+ info_json: _InfoJsonBuildOutputOptions
+
+
+class PkgsListBuildOutput(BaseModel):
+ "The list of packages contained in a given environment."
+
+ model_config: ConfigDict = _base_config_dict
+ pkgs_list: _PkgsListBuildOutputOptions
+
+
+class LockfileBuildOutput(BaseModel):
+ "An `@EXPLICIT` lockfile for a given environment."
+
+ model_config: ConfigDict = _base_config_dict
+ lockfile: _LockfileBuildOutputOptions
+
+
+class LicensesBuildOutput(BaseModel):
+ "Generate a JSON file with the licensing details of all included packages."
+
+ model_config: ConfigDict = _base_config_dict
+ licenses: _LicensesBuildOutputOptions
+
+
+BuildOutputConfigs: TypeAlias = Union[
+ HashBuildOutput,
+ InfoJsonBuildOutput,
+ PkgsListBuildOutput,
+ LockfileBuildOutput,
+ LicensesBuildOutput,
+]
+
+
+class ConstructorConfiguration(BaseModel):
+ """
+ Schema for constructor.yaml input files.
+ """
+
+ model_config: ConfigDict = _base_config_dict
+
+ schema_: Annotated[str, Field(min_length=1, alias="$schema")] = (
+ "https://schemas.conda.org/constructor/v0/construct.schema.json"
+ )
+ """
+ JSON Schema URL or path used to validate this input file.
+ """
+ name: Annotated[str, Field(min_length=1, pattern=NAME_REGEX)] = ...
+ """
+ Name of the installer. Names may be composed of letters, numbers,
+ underscores, dashes, and periods, but must not begin or end with a
+ dash or period.
+ """
+ version: Annotated[str, Field(min_length=1, pattern=VERSION_REGEX)] = ...
+ """
+ Version of the installer. Versions may be composed of letters, numbers,
+ underscores, dashes, and periods, but must not begin or end with a
+ dash or period.
+ """
+ channels: list[NonEmptyStr] = []
+ """
+ The conda channels from which packages are retrieved. At least one channel must
+ be supplied, either in `channels` or `channels_remap`.
+
+ See notes in `channels_remap` for details about local channels.
+ """
+ channels_remap: list[ChannelRemap] = []
+ """
+ A list of `src/dest` channel URL pairs. When building the installer, conda will
+ use the `src` channels to solve and fetch the packages. However, the resulting
+ installation will see the packages as coming from the `dest` equivalent.
+ This allows an installer to be built against a different set of channels than
+ will be present when the installer is actually used. Example use:
+
+ ```yaml
+ channels_remap:
+ - src: file:///tmp/a3/conda-bld # [unix]
+ dest: https://repo.anaconda.com/pkgs/main # [unix]
+ - src: file:///D:/tmp/a3/conda-bld # [win]
+ dest: https://repo.anaconda.com/pkgs/main # [win]
+ ```
+
+ At least one channel must be supplied, either in `channels` or `channels_remap`.
+ """
+ specs: list[NonEmptyStr] | NonEmptyStr = []
+ """
+ A list of package specifications; e.g. `python 2.7*`, `pyzmq` or `numpy >=1.8`.
+ The specifications are identical in form and purpose to those that would be
+ included in a `conda create --file` command. Packages may also be specified
+ by an exact URL, e.g.,
+ `https://repo.anaconda.com/pkgs/main/osx-64/openssl-1.0.2o-h26aff7b_0.tar.bz2`.
+ This key can also take a `str` pointing to a requirements file with the same syntax.
+
+ Note: `constructor` relies on `conda`'s Python API to solve the passed
+ specifications. You can still set the `CONDA_SOLVER` environment variable
+ to override system-wide settings for `constructor`. If you are using
+ `constructor` from a non-`base` environment, make sure the
+ configured solver plugin is also installed in that environment.
+ """
+ user_requested_specs: list[NonEmptyStr] = []
+ """
+ A list of package specifications to be recorded as "user-requested" for the
+ initial environment in conda's history file. This information is used by newer
+ versions of conda to better filter its package choices on subsequent installs;
+ for example, if `python=3.6` is included, then conda will always seek versions
+ of packages compatible with Python 3.6. If this option is not provided, it
+ will be set equal to the value of `specs`.
+ """
+ virtual_specs: list[Annotated[str, Field(min_length=3, pattern=r"^__\S+.*$")]] = []
+ """
+ A list of virtual packages that must be satisfied at install time. Virtual
+ packages must start with `__`. For example, `__osx>=11` or `__glibc>=2.24`.
+ These specs are dry-run solved offline by the bundled `--conda-exe` binary.
+ In SH installers, `__glibc>=x.y` and `__osx>=x.y` specs can be checked with
+ Bash only. The detected version can be overriden with environment variables
+ `CONDA_OVERRIDE_GLIBC` and `CONDA_OVERRIDE_OSX`, respectively. In PKG
+ installers, `__osx` specs can be checked natively without the solver being
+ involved as long as only `>=`, `<` or `,` are used.
+ """
+ exclude: list[NonEmptyStr] = []
+ """
+ A list of package names to be excluded after the `specs` have been resolved.
+ For example, you can say that `readline` should be excluded, even though it
+ is contained as a result of resolving the specs for `python 2.7`.
+ """
+ menu_packages: list[NonEmptyStr] | None = None
+ """
+ A list of packages with menu items to be installed. The packages must have
+ necessary metadata in `Menu/.json`. By default, all menu items
+ found in the installation will be created; supplying this list allows a
+ subset to be selected instead. If an empty list is supplied, no shortcuts will
+ be created.
+
+ If all environments (`extra_envs` included) set `menu_packages` to an empty list,
+ no UI options about shortcuts will be offered to the user.
+
+ Note: This option is not fully implemented when `micromamba` is used as
+ the `--conda-exe` binary. The only accepted value is an empty list (`[]`).
+ """
+ ignore_duplicate_files: bool = True
+ """
+ By default, constructor will warn you when adding packages with duplicate
+ files in them. Setting this option to false will raise an error instead.
+ """
+ install_in_dependency_order: bool | str = Field(True, deprecated=True)
+ """
+ _Obsolete_. The current version of constructor relies on the standalone
+ conda executable for its installation behavior. This option is now
+ ignored with a warning.
+ """
+ environment: NonEmptyStr | None = None
+ """
+ Name of the environment to construct from. If this option is present, the
+ `specs` argument will be ignored. Using this option allows the user to
+ curate the enviromment interactively using standard `conda` commands, and
+ run constructor with full confidence that the exact environment will be
+ reproduced.
+ """
+ environment_file: NonEmptyStr | None = None
+ """
+ Path to an environment file (TXT or YAML) to construct from. If this option
+ is present, the `specs` argument will be ignored. Instead, constructor will
+ call conda to create a temporary environment, constructor will build an
+ installer from that, and the temporary environment will be removed.
+ This ensures that constructor is using the precise local conda configuration
+ to discover and install the packages. The created environment MUST include
+ `python`.
+
+ See notes about the solver in the `specs` field for more information.
+ """
+ transmute_file_type: Literal[".conda"] | None = None
+ """
+ File type extension for the files to be transmuted into.
+ If left empty, no transmuting is done.
+ """
+ conda_default_channels: list[NonEmptyStr] = []
+ """
+ If this value is provided as well as `write_condarc`, then the channels
+ in this list will be included as the value of the `default_channels:`
+ option in the environment's `.condarc` file. This will have an impact
+ only if `conda` is included in the environmnent.
+ """
+ conda_channel_alias: NonEmptyStr | None = None
+ """
+ The channel alias that would be assumed for the created installer
+ (only useful if it includes `conda`).
+ """
+ extra_envs: dict[Annotated[str, Field(min_length=1, pattern=ENV_NAME_REGEX)], ExtraEnv] = {}
+ """
+ Create more environments in addition to the default `base` provided by `specs`,
+ `environment` or `environment_file`.
+
+ Notes:
+ - `ignore_duplicate_files` will always be considered `True` if `extra_envs` is in use.
+ - `conda` needs to be present in the `base` environment (via `specs`)
+ - If a global `exclude` option is used, it will have an effect on the environments created
+ by `extra_envs` too. For example, if the global environment excludes `tk`, none of the
+ extra environments will have it either. Unlike the global option, an error will not be
+ thrown if the excluded package is not found in the packages required by the extra environment.
+ To override the global `exclude` value, use an empty list `[]`.
+ """
+ register_envs: bool = True
+ """
+ Whether to register the environments created by the installer (both `base` and `extra_envs`)
+ in `~/.conda/environments.txt`. Only compatible with conda-standalone >=23.9.
+ """
+ installer_filename: NonEmptyStr | None = None
+ """
+ The filename of the installer being created. If not supplied, a reasonable
+ default will be determined by the `name`, `version`, `platform`, and `installer_type`.
+ """
+ installer_type: InstallerTypes | list[InstallerTypes] | None = None
+ """
+ The type of the installer being created. Possible values are:
+ - `sh`: shell-based installer for Linux or macOS
+ - `pkg`: macOS GUI installer built with Apple's `pkgbuild`
+ - `exe`: Windows GUI installer built with NSIS
+
+ The default type is `sh` on Linux and macOS, and `exe` on Windows. A special
+ value of `all` builds _both_ `sh` and `pkg` installers on macOS, as well
+ as `sh` on Linux and `exe` on Windows.
+
+ """
+ license_file: NonEmptyStr | None = None
+ """
+ Path to the license file being displayed by the installer during the install
+ process. It must be plain text (.txt) for shell-based installers. For PKG,
+ .txt, .rtf and .html are supported. On Windows, .txt and .rtf are supported.
+ """
+ keep_pkgs: bool = False
+ """
+ If `False`, the package cache in the `pkgs` subdirectory is removed
+ when the installation process is complete. If `True`, this subdirectory and
+ its contents are preserved. If `keep_pkgs` is `False`, Unix `.sh` and Windows `.exe`
+ installers offer a command-line option (`-k` and `/KeepPkgCache`, respectively)
+ to preserve the package cache.
+ """
+ batch_mode: bool = False
+ """
+ Only affects `.sh` installers. If `False`, the installer launches
+ an interactive wizard guiding the user through the available options. If
+ `True`, the installer runs automatically as if `-b` was passed.
+ """
+ signing_identity_name: NonEmptyStr | None = None
+ """
+ By default, the MacOS pkg installer isn't signed. If an identity name is specified
+ using this option, it will be used to sign the installer with Apple's `productsign`.
+ Note that you will need to have a certificate (usually an "Installer certificate")
+ and the corresponding private key, together called an 'identity', in one of your
+ accessible keychains. Common values for this option follow this format
+ `Developer ID Installer: Name of the owner (XXXXXX)`.
+ """
+ notarization_identity_name: NonEmptyStr | None = None
+ """
+ If the pkg installer is going to be signed with `signing_identity_name`, you
+ can also prepare the bundle for notarization. This will use Apple's `codesign`
+ to sign `conda.exe`. For this, you need an "Application certificate" (different from the
+ "Installer certificate" mentioned above). Common values for this option follow the format
+ `Developer ID Application: Name of the owner (XXXXXX)`.
+ """
+ windows_signing_tool: WinSignTools | None = None
+ """
+ The tool used to sign Windows installers. Must be one of: azuresigntool, signtool.
+ Some tools require `signing_certificate` to be set.
+ Defaults to `signtool` if `signing_certificate` is set.
+ Additional environment variables may need to be used to configure signing.
+ See the documentation for details:
+ https://conda.github.io/constructor/howto/#signing-exe-installers
+ """
+ signing_certificate: NonEmptyStr | None = None
+ """
+ On Windows only, set this key to the path of the certificate file to be used
+ with the `windows_signing_tool`.
+ """
+ attempt_hardlinks: bool | str = Field(True, deprecated=True)
+ """
+ _Obsolete_. The current version of constructor relies on the standalone
+ conda executable for its installation behavior. This option is now
+ ignored with a warning.
+ """
+ write_condarc: bool = False
+ """
+ By default, no `.condarc` file is written. If set, a `.condarc` file is written to
+ the installation directory if there are any channels or `conda_default_channels` is set.
+ """
+ condarc: NonEmptyStr | dict | None = None
+ """
+ If set, a `.condarc` file is written to the base environment containing the contents
+ of this value. The value can either be a string (likely a multi-line string) or
+ a dictionary, which will be converted to a YAML string for writing. _Note:_ if this
+ option is used, then all other options related to the construction of a `.condarc`
+ file (`write_condarc`, `conda_default_channels`, etc.) are ignored.
+ """
+ company: NonEmptyStr | None = None
+ """
+ Name of the company/entity responsible for the installer.
+ """
+ reverse_domain_identifier: NonEmptyStr | None = None
+ """
+ Unique identifier for this package, formatted with reverse domain notation. This is
+ used internally in the PKG installers to handle future updates and others. If not
+ provided, it will default to `io.continuum`. (MacOS only)
+ """
+ uninstall_name: NonEmptyStr | None = None
+ """
+ Application name in the Windows "Programs and Features" control panel.
+ Defaults to `${NAME} ${VERSION} (Python ${PYVERSION} ${ARCH})`.
+ """
+ script_env_variables: dict[NonEmptyStr, str] = {}
+ """
+ Dictionary of additional environment variables to be made available to
+ the pre_install and post_install scripts, in the form of VAR:VALUE
+ pairs. These environment variables are in addition to those in the
+ `post_install` section above and take precedence in the case of name
+ collisions.
+
+ On Unix the variable values are automatically single quoted, allowing
+ you to supply strings with spaces, without needing to worry about
+ escaping. As a consequence, string interpolation is disabled: if you
+ need string interpolation, you can apply it in the
+ pre_install/post_install script(s). If you need to include single quotes
+ in your value, you can escape them by replacing each single quote with
+ `'''`.
+
+ On Windows, single quotes and double quotes are not supported.
+
+ Note that the # (hash) character cannot be used as it denotes yaml
+ comments for all platforms.
+ """
+ pre_install: NonEmptyStr | None = None
+ """
+ Path to a pre-install script, run after the package cache has been set, but
+ before the files are linked to their final locations. As a result, you should
+ only rely on tools known to be available on most systems (e.g. `bash`, `cmd`,
+ etc). See `post_install` for information about available environment variables.
+ """
+ pre_install_desc: NonEmptyStr | None = None
+ """
+ A description of the purpose of the supplied `pre_install` script. If this
+ string is supplied and non-empty, then the Windows and macOS GUI installers
+ will display it along with a checkbox to enable or disable the execution of the
+ script. If this string is not supplied, it is assumed that the script
+ is compulsory and the option to disable it will not be offered.
+
+ This option has no effect on `SH` installers.
+ """
+ post_install: NonEmptyStr | None = None
+ """
+ Path to a post-install script. Some notes:
+
+ - For Unix `.sh` installers, the shebang line is respected if present;
+ otherwise, the script is run by the POSIX shell `sh`. Note that the use
+ of a shebang can reduce the portability of the installer. The
+ installation path is available as `${PREFIX}`. Installer metadata is
+ available in the `${INSTALLER_NAME}`, `${INSTALLER_VER}`, `${INSTALLER_PLAT}`
+ environment variables. `${INSTALLER_TYPE}` is set to `SH`.
+ `${INSTALLER_UNATTENDED}` will be `"1"` in batch mode (`-b`), `"0"` otherwise.
+ - For PKG installers, the shebang line is respected if present;
+ otherwise, `bash` is used. The same variables mentioned for `sh`
+ installers are available here. `${INSTALLER_TYPE}` is set to `PKG`.
+ `${INSTALLER_UNATTENDED}` will be `"1"` for command line installs, `"0"` otherwise.
+ - For Windows `.exe` installers, the script must be a `.bat` file.
+ Installation path is available as `%PREFIX%`. Metadata about
+ the installer can be found in the `%INSTALLER_NAME%`, `%INSTALLER_VER%`,
+ `%INSTALLER_PLAT%` environment variables. `%INSTALLER_TYPE%` is set to `EXE`.
+ `%INSTALLER_UNATTENDED%` will be `"1"` in silent mode (`/S`), `"0"` otherwise.
+
+ If necessary, you can activate the installed `base` environment like this:
+
+ - Unix: `. "$PREFIX/etc/profile.d/conda.sh" && conda activate "$PREFIX"`
+ - Windows: `call "%PREFIX%\\Scripts\\activate.bat"`
+ """
+ post_install_desc: NonEmptyStr | None = None
+ """
+ A description of the purpose of the supplied `post_install` script. If this
+ string is supplied and non-empty, then the Windows and macOS GUI installers
+ will display it along with a checkbox to enable or disable the execution of the
+ script. If this string is not supplied, it is assumed that the script
+ is compulsory and the option to disable it will not be offered.
+
+ This option has no effect on `SH` installers.
+ """
+ pre_uninstall: NonEmptyStr | None = None
+ """
+ Path to a pre uninstall script. This is only supported on Windows,
+ and must be a `.bat` file. Installation path is available as `%PREFIX%`.
+ Metadata about the installer can be found in the `%INSTALLER_NAME%`,
+ `%INSTALLER_VER%`, `%INSTALLER_PLAT%` environment variables.
+ `%INSTALLER_TYPE%` is set to `EXE`.
+ """
+ default_prefix: NonEmptyStr | None = None
+ """
+ Set default install prefix. On Linux, if not provided, the default prefix
+ is `${HOME}/` (or, if `HOME` is not set, `/opt/`). On Windows,
+ this is used only for "Just Me" installations; for "All Users" installations,
+ use the `default_prefix_all_users` key. If not provided, the default prefix
+ is `%USERPROFILE%\\`. Environment variables will be expanded at
+ install time.
+ """
+ default_prefix_domain_user: NonEmptyStr | None = None
+ """
+ Set default installation prefix for domain users. If not provided, the
+ installation prefix for domain users will be `%LOCALAPPDATA%\\`.
+ By default, it is different from the `default_prefix` value to avoid installing
+ the distribution into the roaming profile. Environment variables will be expanded
+ at install time. Windows only.
+ """
+ default_prefix_all_users: NonEmptyStr | None = None
+ """
+ Set default installation prefix for All Users installations. If not provided,
+ the installation prefix will be `%ALLUSERSPROFILE%\\`.
+ Environment variables will be expanded at install time. Windows only.
+ """
+ default_location_pkg: NonEmptyStr | None = None
+ """
+ Default installation subdirectory in the chosen volume. In PKG installers,
+ default installation locations are configured differently. The user can choose
+ between a "Just me" installation (which would result in `~/`) or another
+ volume (which defaults to `/`). If you want a different default,
+ you can add a middle component with this option, let's call it `location`. It would
+ result in these default values: `~//` for "Just me",
+ `//` for custom volumes. For example, setting this option
+ to `/Library` in a "Just me" installation will give you `~/Library/`.
+ Internally, this is passed to `pkgbuild --install-location`.
+ macOS only.
+ """
+ pkg_domains: dict[PkgDomains, bool] = {"enable_anywhere": True, "enable_currentUserHome": False}
+ """
+ The domains the package can be installed into. For a detailed explanation, see:
+ https://developer.apple.com/library/archive/documentation/DeveloperTools/Reference/DistributionDefinitionRef/Chapters/Distribution_XML_Ref.html
+ constructor defaults to `enable_anywhere=true` and `enable_currentUserHome=true`.
+ `enable_localSystem` should not be set to true unless `default_location_pkg` is set as well.
+ macOS only.
+ """
+ pkg_name: NonEmptyStr | None = None
+ """
+ Internal identifier for the installer. This is used in the build prefix and will
+ determine part of the default location path. Combine with `default_location_pkg`
+ for more flexibility. If not provided, the value of `name` will be used. (macOS only)
+ """
+ install_path_exists_error_text: NonEmptyStr | None = None
+ """
+ Error message that will be shown if the installation path already exists.
+ You cannot use double quotes or newlines. The placeholder `{CHOSEN_PATH}` is
+ available and set to the destination causing the error. Defaults to:
+
+ > '{CHOSEN_PATH}' already exists. Please, relaunch the installer and
+ choose another location in the Destination Select step.
+
+ (PKG only)
+ """
+ progress_notifications: bool = False
+ """
+ Whether to show UI notifications on PKG installers. On large installations,
+ the progress bar reaches ~90% very quickly and stays there for a long time.
+ This might look like the installer froze. This option enables UI notifications
+ so the user receives updates after each command executed by the installer.
+ (macOS only)
+ """
+ welcome_image: str | None = None
+ """
+ Path to an image in any common image format (`.png`, `.jpg`, `.tif`, etc.)
+ to be used as the welcome image for the Windows and PKG installers.
+ The image is re-sized to 164 x 314 pixels on Windows and 1227 x 600 on macOS.
+ By default, an image is automatically generated on Windows. On macOS, Anaconda's
+ logo is shown if this key is not provided. If you don't want a background on
+ PKG installers, set this key to `""` (empty string).
+ """
+ header_image: str | None = None
+ """
+ Like `welcome_image` for Windows, re-sized to 150 x 57 pixels.
+ """
+ icon_image: str | None = None
+ """
+ Like `welcome_image` for Windows, re-sized to 256 x 256 pixels.
+ """
+ default_image_color: Literal["red", "green", "blue", "yellow"] = "blue"
+ """
+ The color of the default images (when not providing explicit image files)
+ used on Windows.
+ """
+ welcome_image_text: NonEmptyStr | None = None
+ """
+ If `welcome_image` is not provided, use this text when generating the image
+ (Windows and PKG only). Defaults to `name` on Windows.
+ """
+ header_image_text: NonEmptyStr | None = None
+ """
+ If `header_image` is not provided, use this text when generating the image
+ (Windows only). Defaults to `name`.
+ """
+ initialize_conda: bool = True
+ """
+ Add an option to the installer so the user can choose whether to run `conda init`
+ after the installation (Unix), or to add certain subdirectories of the installation
+ to PATH (Windows). See also `initialize_by_default`.
+ """
+ initialize_by_default: bool | None = None
+ """
+ Default value for the option added by `initialize_conda`. The default
+ is true for GUI installers (EXE, PKG) and false for shell installers. The user
+ is able to change the default during interactive installation. NOTE: For Windows,
+ `AddToPath` is disabled when `InstallationType=AllUsers`.
+
+ Only applies if `initialize_conda` is true.
+ """
+ register_python: bool = True
+ """
+ Whether to offer the user an option to register the installed Python instance as the
+ system's default Python. (Windows only)
+ """
+ register_python_default: bool | None = False
+ """
+ Default choice for whether to register the installed Python instance as the
+ system's default Python. The user is still able to change this during
+ interactive installation. (Windows only).
+
+ Only applies if `register_python` is true.
+ """
+ check_path_length: bool | None = None
+ """
+ Check the length of the path where the distribution is installed to ensure nodejs
+ can be installed. Raise a message to request shorter paths (less than 46 character)
+ or enable long paths on windows > 10 (require admin right). Default is True. (Windows only).
+ """
+ check_path_spaces: bool = True
+ """
+ Check if the path where the distribution is installed contains spaces.
+ To allow installations with spaces, change to False. Note that:
+
+ - A recent conda-standalone (>=22.11.1) or equivalent is needed for full support.
+ - `conda` cannot be present in the `base` environment
+ """
+ nsis_template: NonEmptyStr | None = None
+ """
+ Path to an NSIS template file to use instead of the default template. (Windows only)
+ """
+ welcome_file: NonEmptyStr | None = None
+ """
+ If `installer_type` is `pkg` on macOS, this message will be
+ shown before the license information, right after the introduction.
+ File can be plain text (.txt), rich text (.rtf) or HTML (.html). If
+ both `welcome_file` and `welcome_text` are provided, `welcome_file` takes precedence.
+
+ If the installer is for Windows and the welcome file type is nsi,
+ it will use the nsi script to add in extra pages before the installer
+ begins the installation process.
+ """
+ welcome_text: str | None = None
+ """
+ If `installer_type` is `pkg` on macOS, this message will be
+ shown before the license information, right after the introduction.
+ If this key is missing, it defaults to a message about Anaconda Cloud.
+ You can disable it altogether so it defaults to the system message
+ if you set this key to `""` (empty string).
+ """
+ readme_file: NonEmptyStr | None = None
+ """
+ If `installer_type` is `pkg` on macOS, this message will be
+ shown before the license information, right after the welcome screen.
+ File can be plain text (.txt), rich text (.rtf) or HTML (.html). If
+ both `readme_file` and `readme_text` are provided, `readme_file` takes precedence.
+ """
+ readme_text: str | None = None
+ """
+ If `installer_type` is `pkg` on macOS, this message will be
+ shown before the license information, right after the welcome screen.
+ If this key is missing, it defaults to a message about Anaconda Cloud.
+ You can disable it altogether if you set this key to `""` (empty string).
+ """
+ post_install_pages: NonEmptyStr | list[NonEmptyStr] | None = None
+ """
+ Adds extra pages to the installers to be shown after installation.
+
+ For PKG installers, these can be compiled `installer` plug-ins or
+ directories containing an Xcode project. In the latter case,
+ constructor will try and compile the project file using `xcodebuild`.
+
+ For Windows, the extra pages must be `.nsi` files.
+ They will be inserted as-is before the conclusion page.
+ """
+ conclusion_file: NonEmptyStr | None = None
+ """
+ If `installer_type` is `pkg` on macOS, this message will be
+ shown at the end of the installer upon success. File can be
+ plain text (.txt), rich text (.rtf) or HTML (.html). If both
+ `conclusion_file` and `conclusion_text` are provided,
+ `conclusion_file` takes precedence.
+
+ If the installer is for Windows, the file type must be nsi.
+ """
+ conclusion_text: str | None = None
+ """
+ A message that will be shown at the end of the installer upon success.
+ The behaviour is slightly different across installer types:
+ - PKG: If this key is missing, it defaults to a message about Anaconda Cloud.
+ You can disable it altogether so it defaults to the system message if you set this
+ key to `""` (empty string).
+ - EXE: The first line will be used as a title. The following lines will be used as text.
+ """
+ extra_files: list[NonEmptyStr | dict[NonEmptyStr, NonEmptyStr]] = []
+ """
+ Extra, non-packaged files that should be added to the installer. If provided as relative
+ paths, they will be considered relative to the directory where `construct.yaml` is.
+ This setting can be passed as a list of:
+ - `str`: each found file will be copied to the root prefix
+ - `Mapping[str, str]`: map of path in disk to path in prefix.
+ """
+ temp_extra_files: list[NonEmptyStr | dict[NonEmptyStr, NonEmptyStr]] = []
+ """
+ Temporary files that could be referenced in the installation process (i.e. customized
+ `welcome_file` and `conclusion_file`). Should be a list of
+ file paths, relative to the directory where `construct.yaml` is. In Windows, these
+ files will be copied into a temporary folder, the NSIS `$PLUGINSDIR`, during
+ the install process (Windows only).
+
+ Supports the same values as `extra_files`.
+ """
+ build_outputs: list[BuildOutputs | BuildOutputConfigs] = Field(
+ # Need a Field to render the description docstring dynamically
+ [],
+ description=cleandoc(
+ """
+ Additional artifacts to be produced after building the installer.
+ It expects either a list of strings or single-key dictionaries.
+
+ Allowed strings / keys: {}.
+ """.format(", ".join([f"`{v}`" for v in BuildOutputs.__members__.values()])),
+ ),
+ )
+ uninstall_with_conda_exe: bool | None = None
+ """
+ Use the standalone binary to perform the uninstallation on Windows.
+ Requires conda-standalone 24.11.0 or newer.
+ """
+
+
+def fix_descriptions(obj):
+ for key, value in obj.items():
+ if isinstance(value, dict):
+ obj[key] = fix_descriptions(value)
+ if key == "description" and isinstance(value, str):
+ codeblocks = re.findall(r"```.*```", value, flags=re.MULTILINE | re.DOTALL)
+ for i, codeblock in enumerate(codeblocks):
+ value = value.replace(codeblock, f"__CODEBLOCK_{i}__")
+ value = (
+ value.replace("\n\n", "__NEWLINE__")
+ .replace("\n-", "__NEWLINE__-")
+ .replace("\n", " ")
+ .replace(" ", " ")
+ .replace("__NEWLINE__", "\n")
+ )
+ for i, codeblock in enumerate(codeblocks):
+ value = value.replace(f"__CODEBLOCK_{i}__", codeblock)
+ obj[key] = value
+
+ return obj
+
+
+def checks():
+ from constructor.build_outputs import OUTPUT_HANDLERS
+
+ if sorted(BuildOutputs.__members__.values()) != sorted(OUTPUT_HANDLERS.keys()):
+ print(sorted(BuildOutputs.__members__.values()))
+ print("!=")
+ print(sorted(OUTPUT_HANDLERS.keys()))
+ raise AssertionError(
+ "Need to sync constructor.build_outputs.OUTPUT_HANDLERS "
+ "with constructor._schema.BuildOutputs enum."
+ )
+
+
+def dump_schema():
+ model = ConstructorConfiguration(name="doesnotmatter", version="0.0.0")
+ obj = model.model_json_schema()
+ obj = fix_descriptions(obj)
+ obj["$schema"] = "https://json-schema.org/draft/2020-12/schema"
+ SCHEMA_PATH.write_text(json.dumps(obj, sort_keys=True, indent=2) + "\n")
+ print(json.dumps(obj, sort_keys=True, indent=2))
+
+
+if __name__ == "__main__":
+ checks()
+ dump_schema()
diff --git a/constructor/construct.py b/constructor/construct.py
index e332b7399..1bb411ec6 100644
--- a/constructor/construct.py
+++ b/constructor/construct.py
@@ -7,973 +7,27 @@
Defines the construct.yaml input file schema, how to parse it and verify it.
"""
+from __future__ import annotations
+
+import json
import logging
import re
import sys
from functools import partial
from os.path import dirname
+from pathlib import Path
+from jsonschema import Draft202012Validator, validators
+from jsonschema.exceptions import ValidationError
from ruamel.yaml import YAMLError
from constructor.exceptions import UnableToParse, UnableToParseMissingJinja2, YamlParsingError
from constructor.utils import yaml
-WIN_SIGNTOOLS = [
- "azuresigntool",
- "signtool",
-]
-
-# list of tuples (key name, required, type, description)
-KEYS = [
- (
- "name",
- True,
- str,
- """
-Name of the installer. Names may be composed of letters, numbers,
-underscores, dashes, and periods, but may not begin or end with a
-dash or period.
-""",
- ),
- (
- "version",
- True,
- str,
- """
-Version of the installer. Versions may be composed of letters, numbers,
-underscores, dashes, and periods, but may not begin or end with a
-dash or period.
-""",
- ),
- (
- "channels",
- False,
- list,
- """
-The conda channels from which packages are retrieved. At least one channel must
-be supplied, either in `channels` or `channels_remap`.
-
-See notes in `channels_remap` for details about local channels.
-""",
- ),
- (
- "channels_remap",
- False,
- list,
- """
-A list of `src/dest` channel URL pairs. When building the installer, conda will
-use the `src` channels to solve and fetch the packages. However, the resulting
-installation will see the packages as coming from the `dest` equivalent.
-This allows an installer to be built against a different set of channels than
-will be present when the installer is actually used. Example use:
-
-```yaml
-channels_remap:
- - src: file:///tmp/a3/conda-bld # [unix]
- dest: https://repo.anaconda.com/pkgs/main # [unix]
- - src: file:///D:/tmp/a3/conda-bld # [win]
- dest: https://repo.anaconda.com/pkgs/main # [unix]
-```
-
-At least one channel must be supplied, either in `channels` or `channels_remap`.
-""",
- ),
- (
- "specs",
- False,
- (list, str),
- """
-A list of package specifications; e.g. `python 2.7*`, `pyzmq` or `numpy >=1.8`.
-The specifications are identical in form and purpose to those that would be
-included in a `conda create --file` command. Packages may also be specified
-by an exact URL; e.g.,
-`https://repo.anaconda.com/pkgs/main/osx-64/openssl-1.0.2o-h26aff7b_0.tar.bz2`.
-This key can also take a `str` pointing to a requirements file with the same syntax.
-
-Note: `constructor` relies on `conda`'s Python API to solve the passed
-specifications. You can still set the `CONDA_SOLVER` environment variable
-to override system-wide settings for `constructor`. If you are using
-`constructor` from a non-`base` environment, make sure the
-configured solver plugin is also installed in that environment.
-""",
- ),
- (
- "user_requested_specs",
- False,
- (list, str),
- """
-A list of package specifications to be recorded as "user-requested" for the
-initial environment in conda's history file. This information is used by newer
-versions of conda to better filter its package choices on subsequent installs;
-for example, if `python=3.6` is included, then conda will always seek versions
-of packages compatible with Python 3.6. If this is option is not provided, it
-will be set equal to the value of `specs`.
-""",
- ),
- (
- "virtual_specs",
- False,
- list,
- """
-A list of virtual packages that must be satisfied at install time. Virtual
-packages must start with `__`. For example, `__osx>=11` or `__glibc>=2.24`.
-These specs are dry-run solved offline by the bundled `--conda-exe` binary.
-In SH installers, `__glibc>=x.y` and `__osx>=x.y` specs can be checked with
-Bash only. The detected version can be overriden with environment variables
-`CONDA_OVERRIDE_GLIBC` and `CONDA_OVERRIDE_OSX`, respectively. In PKG
-installers, `__osx` specs can be checked natively without the solver being
-involved as long as only `>=`, `<` or `,` are used.
-""",
- ),
- (
- "exclude",
- False,
- list,
- """
-A list of package names to be excluded after the `specs` have been resolved.
-For example, you can say that `readline` should be excluded, even though it
-is contained as a result of resolving the specs for `python 2.7`.
-""",
- ),
- (
- "menu_packages",
- False,
- list,
- """
-A list of packages with menu items to be installed. The packages must have
-necessary metadata in `Menu/.json`). By default, all menu items
-found in the installation will be created; supplying this list allows a
-subset to be selected instead. If an empty list is supplied, no shortcuts will
-be created.
-
-If all environments (`extra_envs` included) set `menu_packages` to an empty list,
-no UI options about shortcuts will be offered to the user.
-
-Note: This option is not fully implemented when `micromamba` is used as
-the `--conda-exe` binary. The only accepted value is an empty list (`[]`).
-""",
- ),
- (
- "ignore_duplicate_files",
- False,
- bool,
- """
-By default, constructor will warn you when adding packages with duplicate
-files in them. Setting this option to false will raise an error instead.
-""",
- ),
- (
- "install_in_dependency_order",
- False,
- (bool, str),
- """
-_Obsolete_. The current version of constructor relies on the standalone
-conda executable for its installation behavior. This option is now
-ignored with a warning.
-""",
- ),
- (
- "environment",
- False,
- str,
- """
-Name of the environment to construct from. If this option is present, the
-`specs` argument will be ignored. Using this option allows the user to
-curate the enviromment interactively using standard `conda` commands, and
-run constructor with full confidence that the exact environment will be
-reproduced.
-""",
- ),
- (
- "environment_file",
- False,
- str,
- """
-Path to an environment file (TXT or YAML) to construct from. If this option
-is present, the `specs` argument will be ignored. Instead, constructor will
-call conda to create a temporary environment, constructor will build and
-installer from that, and the temporary environment will be removed.
-This ensures that constructor is using the precise local conda configuration
-to discover and install the packages. The created environment MUST include
-`python`.
-
-Read notes about the solver in the `specs` field.
-""",
- ),
- (
- "transmute_file_type",
- False,
- str,
- """
-File type extension for the files to be transmuted into. Currently supports
-only '.conda'. See conda-package-handling for supported extension names.
-If left empty, no transmuting is done.
-""",
- ),
- (
- "conda_default_channels",
- False,
- list,
- """
-If this value is provided as well as `write_condarc`, then the channels
-in this list will be included as the value of the `default_channels:`
-option in the environment's `.condarc` file. This will have an impact
-only if `conda` is included in the environmnent.
-""",
- ),
- (
- "conda_channel_alias",
- False,
- str,
- """
-The channel alias that would be assumed for the created installer
-(only useful if it includes conda).
-""",
- ),
- (
- "extra_envs",
- False,
- (dict,),
- """
-Create more environments in addition to the default `base` provided by `specs`,
-`environment` or `environment_file`. This should be a map of `str` (environment
-name) to a dictionary of options:
-- `specs` (list of str): which packages to install in that environment
-- `environment` (str): same as global option, for this env
-- `environment_file` (str): same as global option, for this env
-- `channels` (list of str): using these channels; if not provided, the global
- value is used. To override inheritance, set it to an empty list.
-- `channels_remap` (list of str): same as global option, for this env;
- if not provided, the global value is used. To override inheritance, set it to
- an empty list.
-- `user_requested_specs` (list of str): same as the global option, but for this env;
- if not provided, global value is _not_ used
-- `menu_packages` (list of str): same as the global option, for this env;
- if not provided, the global value is _not_ used.
-
-Notes:
-- `ignore_duplicate_files` will always be considered `True` if `extra_envs` is in use.
-- `conda` needs to be present in the `base` environment (via `specs`)
-- If a global `exclude` option is used, it will have an effect on the environments created
- by `extra_envs` too. For example, if the global environment excludes `tk`, none of the
- extra environments will have it either. Unlike the global option, an error will not be
- thrown if the excluded package is not found in the packages required by the extra environment.
- To override the global `exclude` value, use an empty list `[]`.
-""",
- ),
- (
- "register_envs",
- False,
- bool,
- """
-Whether to register the environments created by the installer (both `base` and `extra_envs`)
-in `~/.conda/environments.txt`. Only compatible with conda-standalone >=23.9. Defaults to `True`.
-""",
- ),
- (
- "installer_filename",
- False,
- str,
- """
-The filename of the installer being created. If not supplied, a reasonable
-default will determined by the `name`, `version`, platform, and installer type.
-""",
- ),
- (
- "installer_type",
- False,
- (str, list),
- """
-The type of the installer being created. Possible values are:
-- `sh`: shell-based installer for Linux or macOS;
-- `pkg`: macOS GUI installer built with Apple's `pkgbuild`
-- `exe`: Windows GUI installer built with NSIS
-
-The default type is `sh` on Linux and macOS, and `exe` on Windows. A special
-value of `all` builds _both_ `sh` and `pkg` installers on macOS, as well
-as `sh` on Linux and `exe` on Windows.
-
-Notes for silent mode `/S` on Windows EXEs:
-- NSIS Silent mode will not print any error message, but will silently abort the installation.
- If needed, [NSIS log-builds][nsis-log] can be used to print to `%PREFIX%\\install.log`, which
- can be searched for `::error::` strings. Pre- and post- install scripts will only throw an error
- if the environment variable `NSIS_SCRIPTS_RAISE_ERRORS` is set.
-- The `/D` flag can be used to specify the target location. It must be the last argument in
- the command and should NEVER be quoted, even if it contains spaces. For example:
- `CMD.EXE /C START /WAIT myproject.exe /S /D=C:\\path with spaces\\my project`.
-
-[nsis-log]: https://nsis.sourceforge.io/Special_Builds
-""",
- ),
- (
- "license_file",
- False,
- str,
- """
-Path to the license file being displayed by the installer during the install
-process. It must be plain text (.txt) for shell-based installers. On PKG,
-.txt, .rtf and .html are supported. On Windows, .txt and .rtf are supported.
-""",
- ),
- (
- "keep_pkgs",
- False,
- bool,
- """
-If `False` (default), the package cache in the `pkgs` subdirectory is removed
-when the installation process is complete. If `True`, this subdirectory and
-its contents are preserved. If `keep_pkgs` is `False`, Unix `.sh` and Windows `.msi`
-installers offer a command-line option (`-k` and `/KeepPkgCache`, respectively)
-to preserve the package cache.
-""",
- ),
- (
- "batch_mode",
- False,
- bool,
- """
-Only affects ``.sh`` installers. If ``False`` (default), the installer launches
-an interactive wizard guiding the user through the available options. If
-``True``, the installer runs automatically as if ``-b`` was passed.
-""",
- ),
- (
- "signing_identity_name",
- False,
- str,
- """
-By default, the MacOS pkg installer isn't signed. If an identity name is specified
-using this option, it will be used to sign the installer with Apple's `productsign`.
-Note that you will need to have a certificate (usually an "Installer certificate")
-and the corresponding private key, together called an 'identity', in one of your
-accessible keychains. Common values for this option follow this format
-`Developer ID Installer: Name of the owner (XXXXXX)`.
-""",
- ),
- (
- "notarization_identity_name",
- False,
- str,
- """
-If the pkg installer is going to be signed with `signing_identity_name`, you
-can also prepare the bundle for notarization. This will use Apple's `codesign`
-to sign `conda.exe`. For this, you need an "Application certificate" (different from the
-"Installer certificate" mentioned above). Common values for this option follow the format
-`Developer ID Application: Name of the owner (XXXXXX)`.
-""",
- ),
- (
- "windows_signing_tool",
- False,
- str,
- f"""
-The tool used to sign Windows installers. Must be one of: {", ".join(WIN_SIGNTOOLS)}.
-Some tools require `signing_certificate` to be set.
-Defaults to `signtool` if `signing_certificate` is set.
-Additional environment variables may need to be used to configure signing.
-See the documentation for details:
-https://conda.github.io/constructor/howto/#signing-exe-installers
-""",
- ),
- (
- "signing_certificate",
- False,
- str,
- """
-On Windows only, set this key to the path of the certificate file to be used
-with the `windows_signing_tool`.
-""",
- ),
- (
- "attempt_hardlinks",
- False,
- (bool, str),
- """
-_Obsolete_. The current version of constructor relies on the standalone
-conda executable for its installation behavior. This option is now
-ignored with a warning.
-""",
- ),
- (
- "write_condarc",
- False,
- bool,
- """
-By default, no `.condarc` file is written. If set, a `.condarc` file is written to
-the base environment if there are any channels or conda_default_channels is set.
-""",
- ),
- (
- "condarc",
- False,
- (dict, str),
- """
-If set, a `.condarc` file is written to the base environment containing the contents
-of this value. The value can either be a string (likely a multi-line string) or
-a dictionary, which will be converted to a YAML string for writing. _Note:_ if this
-option is used, then all other options related to the construction of a `.condarc`
-file (`write_condarc`, `conda_default_channels`, etc.) are ignored.
-""",
- ),
- (
- "company",
- False,
- str,
- """
-Name of the company/entity who is responsible for the installer.
-""",
- ),
- (
- "reverse_domain_identifier",
- False,
- str,
- """
-Unique identifier for this package, formatted with reverse domain notation. This is
-used internally in the PKG installers to handle future updates and others. If not
-provided, it will default to `io.continuum`. (MacOS only)
-""",
- ),
- (
- "uninstall_name",
- False,
- str,
- """
-Application name in the Windows "Programs and Features" control panel.
-Defaults to `${NAME} ${VERSION} (Python ${PYVERSION} ${ARCH})`.
-""",
- ),
- (
- "script_env_variables",
- False,
- (dict,),
- """
-Dictionary of additional environment variables to be made available to
-the pre_install and post_install scripts, in the form of VAR:VALUE
-pairs. These environment variables are in addition to those in the
-`post_install` section above and take precedence in the case of name
-collisions.
-
-On Unix the variable values are automatically single quoted, allowing
-you to supply strings with spaces, without needing to worry about
-escaping. As a consequence, string interpolation is disabled: if you
-need string interpolation, you can apply it in the
-pre_install/post_install script(s). If you need to include single quotes
-in your value, you can escape them by replacing each single quote with
-`'\''`.
-
-On Windows, single quotes and double quotes are not supported.
-
-Note that the # (hash) character cannot be used as it denotes yaml
-comments for all platforms.
-""",
- ),
- (
- "pre_install",
- False,
- str,
- """
-Path to a pre-install script, run after the package cache has been set, but
-before the files are linked to their final locations. As a result, you should
-only rely on tools known to be available on most systems (e.g. `bash`, `cmd`,
-etc). See `post_install` for information about available environment variables.
-""",
- ),
- (
- "pre_install_desc",
- False,
- str,
- """
-A description of the purpose of the supplied `pre_install` script. If this
-string is supplied and non-empty, then the Windows and macOS GUI installers
-will display it along with checkbox to enable or disable the execution of the
-script. If this string is not supplied, it is assumed that the script
-is compulsory and the option to disable it will not be offered.
-
-This option has no effect on `SH` installers.
-""",
- ),
- (
- "post_install",
- False,
- str,
- """
-Path to a post-install script. Some notes:
-
-- For Unix `.sh` installers, the shebang line is respected if present;
- otherwise, the script is run by the POSIX shell `sh`. Note that the use
- of a shebang can reduce the portability of the installer. The
- installation path is available as `${PREFIX}`. Installer metadata is
- available in the `${INSTALLER_NAME}`, `${INSTALLER_VER}`, `${INSTALLER_PLAT}`
- environment variables. `${INSTALLER_TYPE}` is set to `SH`.
- `${INSTALLER_UNATTENDED}` will be `"1"` in batch mode (`-b`), `"0"` otherwise.
-- For PKG installers, the shebang line is respected if present;
- otherwise, `bash` is used. The same variables mentioned for `sh`
- installers are available here. `${INSTALLER_TYPE}` is set to `PKG`.
- `${INSTALLER_UNATTENDED}` will be `"1"` for command line installs, `"0"` otherwise.
-- For Windows `.exe` installers, the script must be a `.bat` file.
- Installation path is available as `%PREFIX%`. Metadata about
- the installer can be found in the `%INSTALLER_NAME%`, `%INSTALLER_VER%`,
- `%INSTALLER_PLAT%` environment variables. `%INSTALLER_TYPE%` is set to `EXE`.
- `%INSTALLER_UNATTENDED%` will be `"1"` in silent mode (`/S`), `"0"` otherwise.
-
-If necessary, you can activate the installed `base` environment like this:
-
-- Unix: `source "$PREFIX/etc/profile.d/conda.sh" && conda activate "$PREFIX"`
-- Windows: `call "%PREFIX%\\Scripts\\activate.bat"`
-""",
- ),
- (
- "post_install_desc",
- False,
- str,
- """
-A description of the purpose of the supplied `post_install` script. If this
-string is supplied and non-empty, then the Windows and macOS GUI installers
-will display it along with checkbox to enable or disable the execution of the
-script. If this string is not supplied, it is assumed that the script
-is compulsory and the option to disable it will not be offered.
-
-This option has no effect on `SH` installers.
-""",
- ),
- (
- "pre_uninstall",
- False,
- str,
- """
-Path to a pre uninstall script. This is only supported for on Windows,
-and must be a `.bat` file. Installation path is available as `%PREFIX%`.
-Metadata about the installer can be found in the `%INSTALLER_NAME%`,
-`%INSTALLER_VER%`, `%INSTALLER_PLAT%` environment variables.
-`%INSTALLER_TYPE%` is set to `EXE`.
-""",
- ),
- (
- "default_prefix",
- False,
- str,
- r"""
-Set default install prefix. On Linux, if not provided, the default prefix
-is `${HOME}/` (or, if `HOME` is not set, `/opt/`). On Windows,
-this is used only for "Just Me" installation; for "All Users" installation,
-use the `default_prefix_all_users` key. If not provided, the default prefix
-is `%USERPROFILE%\`. Environment variables will be expanded at
-installation time.
-""",
- ),
- (
- "default_prefix_domain_user",
- False,
- str,
- r"""
-Set default installation prefix for domain user. If not provided, the
-installation prefix for domain user will be `%LOCALAPPDATA%\`.
-By default, it is different from the `default_prefix` value to avoid installing
-the distribution in the roaming profile. Environment variables will be expanded
-at installation time. Windows only.
-""",
- ),
- (
- "default_prefix_all_users",
- False,
- str,
- r"""
-Set default installation prefix for All Users installation. If not provided,
-the installation prefix for all users installation will be
-`%ALLUSERSPROFILE%\`. Environment variables will be expanded at installation
-time. Windows only.
-""",
- ),
- (
- "default_location_pkg",
- False,
- str,
- """
-Default installation subdirectory in the chosen volume. In PKG installers,
-default installation locations are configured differently. The user can choose
-between a "Just me" installation (which would result in `~/`) or another
-volume (which defaults to `/`). If you want a different default,
-you can add a middle component with this option, let's call it `location`. It would
-result in these default values: `~//` for "Just me",
-`//` for custom volumes. For example, setting this option
-to `/Library` in a "Just me" installation will give you `~/Library/`.
-Internally, this is passed to `pkgbuild --install-location`.
-macOS only.
-""",
- ),
- (
- "pkg_domains",
- False,
- dict,
- """
-The domains the package can be installed into. For a detailed explanation, see:
-https://developer.apple.com/library/archive/documentation/DeveloperTools/Reference/DistributionDefinitionRef/Chapters/Distribution_XML_Ref.html
-constructor defaults to `enable_anywhere=true` and `enable_currentUserHome=true`.
-`enable_localSystem` should not be set to true unless `default_location_pkg` is set as well.
-macOS only.
-""",
- ),
- (
- "pkg_name",
- False,
- str,
- """
-Internal identifier for the installer. This is used in the build prefix and will
-determine part of the default location path. Combine with `default_location_pkg`
-for more flexibility. If not provided, the value of `name` will be used. (MacOS only)
-""",
- ),
- (
- "install_path_exists_error_text",
- False,
- str,
- """
-Error message that will be shown if the installation path already exists.
-You cannot use double quotes or newlines. The placeholder `{CHOSEN_PATH}` is
-available and set to the destination causing the error. Defaults to:
-
-> '{CHOSEN_PATH}' already exists. Please, relaunch the installer and
-> choose another location in the Destination Select step.
-
-(MacOS only)
-""",
- ),
- (
- "progress_notifications",
- False,
- bool,
- """
-Whether to show UI notifications on PKG installers. On large installations,
-the progress bar reaches ~90% very quickly and stays there for a long time.
-This might look like the installer froze. This option enables UI notifications
-so the user receives updates after each command executed by the installer.
-(macOS only)
-""",
- ),
- (
- "welcome_image",
- False,
- str,
- """
-Path to an image in any common image format (`.png`, `.jpg`, `.tif`, etc.)
-to be used as the welcome image for the Windows and PKG installers.
-The image is re-sized to 164 x 314 pixels on Windows and 1227 x 600 on Macos.
-By default, an image is automatically generated on Windows. On MacOS, Anaconda's
-logo is shown if this key is not provided. If you don't want a background on
-PKG installers, set this key to `""` (empty string).
-""",
- ),
- (
- "header_image",
- False,
- str,
- """
-Like `welcome_image` for Windows, re-sized to 150 x 57 pixels.
-""",
- ),
- (
- "icon_image",
- False,
- str,
- """
-Like `welcome_image` for Windows, re-sized to 256 x 256 pixels.
-""",
- ),
- (
- "default_image_color",
- False,
- str,
- """
-The color of the default images (when not providing explicit image files)
-used on Windows. Possible values are `red`, `green`, `blue`, `yellow`.
-The default is `blue`.
-""",
- ),
- (
- "welcome_image_text",
- False,
- str,
- """
-If `welcome_image` is not provided, use this text when generating the image
-(Windows and PKG only). Defaults to `name` on Windows.
-""",
- ),
- (
- "header_image_text",
- False,
- str,
- """
-If `header_image` is not provided, use this text when generating the image
-(Windows only). Defaults to `name`.
-""",
- ),
- (
- "initialize_conda",
- False,
- bool,
- """
-Add an option to the installer so the user can choose whether to run `conda init`
-after the install. See also `initialize_by_default`.
-""",
- ),
- (
- "initialize_by_default",
- False,
- bool,
- """
-Whether to add the installation to the PATH environment variable. The default
-is true for GUI installers (msi, pkg) and False for shell installers. The user
-is able to change the default during interactive installation. NOTE: For Windows,
-`AddToPath` is disabled when `InstallationType=AllUsers`.
-""",
- ),
- (
- "register_python",
- False,
- bool,
- """
-Whether to offer the user an option to register the installed Python instance as the
-system's default Python. (Windows only)
-""",
- ),
- (
- "register_python_default",
- False,
- bool,
- """
-Default choice for whether to register the installed Python instance as the
-system's default Python. The user is still able to change this during
-interactive installation. (Windows only).
-""",
- ),
- (
- "check_path_length",
- False,
- bool,
- """
-Check the length of the path where the distribution is installed to ensure nodejs
-can be installed. Raise a message to request shorter path (less than 46 character)
-or enable long path on windows > 10 (require admin right). Default is True. (Windows only).
-
-Read notes about the particularities of Windows silent mode `/S` in the
-`installer_type` documentation.
-""",
- ),
- (
- "check_path_spaces",
- False,
- bool,
- """
-Check if the path where the distribution is installed contains spaces. Default is True.
-To allow installations with spaces, change to False. Note that:
-
-- A recent conda-standalone (>=22.11.1) or equivalent is needed for full support.
-- `conda` cannot be present in the `base` environment
-
-Read notes about the particularities of Windows silent mode `/S` in the
-`installer_type` documentation.
-""",
- ),
- (
- "nsis_template",
- False,
- str,
- """
-If `nsis_template` is not provided, constructor uses its default
-NSIS template. For more complete customization for the installation experience,
-provide an NSIS template file. (Windows only).
-""",
- ),
- (
- "welcome_file",
- False,
- str,
- """
-If `installer_type` is `pkg` on MacOS, this message will be
-shown before the license information, right after the introduction.
-File can be plain text (.txt), rich text (.rtf) or HTML (.html). If
-both `welcome_file` and `welcome_text` are provided, `welcome_file` takes precedence.
-(MacOS only).
-
-If the installer is for windows and welcome file type is nsi,
-it will use the nsi script to add in extra pages before the installer
-begins the installation process.
-""",
- ),
- (
- "welcome_text",
- False,
- str,
- """
-If `installer_type` is `pkg` on MacOS, this message will be
-shown before the license information, right after the introduction.
-If this key is missing, it defaults to a message about Anaconda Cloud.
-You can disable it altogether so it defaults to the system message
-if you set this key to `""` (empty string).
-(MacOS only).
-""",
- ),
- (
- "readme_file",
- False,
- str,
- """
-If `installer_type` is `pkg` on MacOS, this message will be
-shown before the license information, right after the welcome screen.
-File can be plain text (.txt), rich text (.rtf) or HTML (.html). If
-both `readme_file` and `readme_text` are provided, `readme_file` takes precedence.
-(MacOS only).
-""",
- ),
- (
- "readme_text",
- False,
- str,
- """
-If `installer_type` is `pkg` on MacOS, this message will be
-shown before the license information, right after the welcome screen.
-If this key is missing, it defaults to a message about Anaconda Cloud.
-You can disable it altogether if you set this key to `""` (empty string).
-(MacOS only).
-""",
- ),
- (
- "post_install_pages",
- False,
- (list, str),
- """
-Adds extra pages to the installers to be shown after installation.
-
-For PKG installers, these can be compiled `installer` plug-ins or
-directories containing an Xcode project. In the latter case,
-constructor will try and compile the project file using `xcodebuild`.
-
-For Windows, the extra pages must be `.nsi` files.
-They will be inserted as-is before the conclusion page.
-""",
- ),
- (
- "conclusion_file",
- False,
- str,
- """
-If `installer_type` is `pkg` on MacOS, this message will be
-shown at the end of the installer upon success. File can be
-plain text (.txt), rich text (.rtf) or HTML (.html). If both
-`conclusion_file` and `conclusion_text` are provided,
-`conclusion_file` takes precedence. (MacOS only).
-
-If the installer is for Windows, the file type must be nsi.
-""",
- ),
- (
- "conclusion_text",
- False,
- str,
- """
-A message that will be shown at the end of the installer upon success.
-The behaviour is slightly different across installer types:
-- PKG: If this key is missing, it defaults to a message about Anaconda Cloud.
- You can disable it altogether so it defaults to the system message if you set this
- key to `""` (empty string).
-- EXE: The first line will be used as a title. The following lines will be used as text.
-(macOS PKG and Windows only).
-""",
- ),
- (
- "extra_files",
- False,
- list,
- """
-Extra, non-packaged files that should be added to the installer. If provided as relative
-paths, they will be considered relative to the directory where `construct.yaml` is.
-This setting can be passed as a list of:
-- `str`: each found file will be copied to the root prefix
-- `Mapping[str, str]`: map of path in disk to path in prefix.
-""",
- ),
- (
- "temp_extra_files",
- False,
- list,
- """
-Temporary files that could be referenced in the installation process (i.e. customized
-`welcome_file` and `conclusion_file` (see above)) . Should be a list of
-file paths, relative to the directory where `construct.yaml` is. In Windows, these
-files will be copied into a temporary folder, the NSIS `$PLUGINSDIR`, during
-install process (Windows only).
-
-Supports the same values as `extra_files`.
-""",
- ),
- (
- "build_outputs",
- False,
- list,
- """
-Additional artifacts to be produced after building the installer.
-It expects either a list of strings or single-key dictionaries:
-Allowed keys are:
-- `hash`: The hash of the installer files. The output file is designed to work with the `shasum`
- command and thus has POSIX line endings, including on Windows. Options:
- - `algorithm` (str or list): The hash algorithm. Must be among `hashlib`'s available algorithms:
- https://docs.python.org/3/library/hashlib.html#hashlib.algorithms_available
-- `info.json`: The internal `info` object, serialized to JSON. Takes no options.
-- `pkgs_list`: The list of packages contained in a given environment. Options:
- - `env` (optional, default=`base`): Name of an environment in `extra_envs` to export.
-- `lockfile`: An `@EXPLICIT` lockfile for a given environment. Options:
- - `env` (optional, default=`base`): Name of an environment in `extra_envs` to export.
-- `licenses`: Generate a JSON file with the licensing details of all included packages. Options:
- - `include_text` (optional bool, default=`False`): Whether to dump the license text in the JSON.
- If false, only the path will be included.
- - `text_errors` (optional str, default=`None`): How to handle decoding errors when reading the
- license text. Only relevant if include_text is True. Any str accepted by open()'s 'errors'
- argument is valid. See https://docs.python.org/3/library/functions.html#open.
-""",
- ),
- (
- "uninstall_with_conda_exe",
- False,
- bool,
- """
-Use the standalone binary to perform the uninstallation.
-Requires conda-standalone 24.11.0 or newer.
-""",
- ),
-]
-
-
-_EXTRA_ENVS_SCHEMA = {
- "specs": (list, tuple),
- "environment": (str,),
- "environment_file": (str,),
- "channels": (list, tuple),
- "channels_remap": (list, tuple),
- "user_requested_specs": (list, tuple),
- "exclude": (list, tuple),
- "menu_packages": (list, tuple),
-}
-
logger = logging.getLogger(__name__)
-
-def generate_key_info_list():
- key_info_list = []
- for key_info in KEYS:
- type_names = {str: "string", list: "list", dict: "dictionary", bool: "boolean"}
- key_types = key_info[2]
- if not isinstance(key_types, (tuple, list)):
- key_types = (key_types,)
- plural = "s" if len(key_types) > 1 else ""
- key_types = ", ".join(type_names.get(k, "") for k in key_types)
- required = "yes" if key_info[1] else "no"
-
- if key_info[3] == "XXX":
- logger.info("Not including %s because the skip sentinel ('XXX') is set", key_info[0])
- continue
-
- key_info_list.append((key_info[0], required, key_types, key_info[3], plural))
- return key_info_list
+HERE = Path(__file__).parent
+SCHEMA_PATH = HERE / "data" / "construct.schema.json"
def ns_platform(platform):
@@ -1079,68 +133,44 @@ def parse(path, platform):
return res
-def verify(info):
- types_key = {} # maps key to types
- required_keys = set()
- obsolete_keys = set()
- for key, required, types, descr in KEYS:
- types_key[key] = types
- if required:
- required_keys.add(key)
- if "Obsolete" in descr:
- obsolete_keys.add(key)
+# this is actually not an error, therefore the naming is okay
+class DeprecatedFieldWarning(ValidationError):
+ pass
- for key in info:
- if key not in types_key:
- sys.exit("Error: unknown key '%s' in construct.yaml" % key)
- elt = info[key]
- if key in obsolete_keys:
- logger.warning("key '%s' is obsolete. Its value '%s' is being ignored.", key, elt)
- types = types_key[key]
- if not isinstance(elt, types):
- sys.exit("Error: key '%s' points to %s,\n expected %s" % (key, type(elt), types))
- for key in required_keys:
- if key not in info:
- sys.exit("Error: Required key '%s' not found in construct.yaml" % key)
+def deprecated_validator(validator, value, instance, schema):
+ if value and instance is not None:
+ print(value)
+ print(instance)
+ print(schema)
+ yield DeprecatedFieldWarning(f"'{schema['title']}' is deprecated.\n{schema['description']}")
- pat = re.compile(r"[\w][\w\-\.]*$")
- for key in "name", "version":
- value = info[key]
- if not pat.match(value) or value.endswith((".", "-")):
- sys.exit("Error: invalid %s '%s'" % (key, value))
- for env_name, env_data in info.get("extra_envs", {}).items():
- disallowed = ("/", " ", ":", "#")
- if any(character in env_name for character in disallowed):
- sys.exit(
- f"Environment names (keys in 'extra_envs') cannot contain any of {disallowed}. "
- f"You tried to use: {env_name}"
- )
- for key, value in env_data.items():
- if key not in _EXTRA_ENVS_SCHEMA:
- sys.exit(f"Key '{key}' not supported in 'extra_envs'.")
- types = _EXTRA_ENVS_SCHEMA[key]
- if not isinstance(value, types):
- types_str = " or ".join([type_.__name__ for type_ in types])
- sys.exit(
- f"Value for 'extra_envs.{env_name}.{key}' must be an instance of {types_str}"
- )
- if signtool := info.get("windows_signing_tool"):
- if signtool.lower().replace(".exe", "") not in WIN_SIGNTOOLS:
- sys.exit(
- "Value for 'windows_signing_tool' must be one of: "
- f"{', '.join(WIN_SIGNTOOLS)}. You tried to use: {signtool}."
- )
- need_cert_file = ["signtool"]
- if signtool in need_cert_file and not info.get("signing_certificate"):
- sys.exit(f"The signing tool {signtool} requires 'signing_certificate' to be set.")
+def get_validator_class():
+ all_validators = dict(Draft202012Validator.VALIDATORS)
+ all_validators["deprecated"] = deprecated_validator
+ return validators.create(
+ meta_schema=Draft202012Validator.META_SCHEMA, validators=all_validators
+ )
-def generate_doc():
- logger.error("generate_doc() is deprecated. Use scripts/make_docs.py instead")
- sys.exit(1)
+def verify(info):
+ schema = json.loads(SCHEMA_PATH.read_text())
+ validator = get_validator_class()(schema)
+ errors = []
+ for error_or_warning in validator.iter_errors(info):
+ if isinstance(error_or_warning, DeprecatedFieldWarning):
+ print("Warning:", error_or_warning, file=sys.stderr)
+ else:
+ errors.append(error_or_warning)
+ if errors:
+ msg = ["Configuration has validation errors:"]
+ for error in errors:
+ msg.append(f"- {error}")
+ sys.exit("\n".join(msg))
-if __name__ == "__main__":
- generate_doc()
+ if signtool := info.get("windows_signing_tool"):
+ need_cert_file = ["signtool", "signtool.exe"]
+ if signtool in need_cert_file and not info.get("signing_certificate"):
+ sys.exit(f"The signing tool '{signtool}' requires 'signing_certificate' to be set.")
diff --git a/constructor/data/construct.schema.json b/constructor/data/construct.schema.json
new file mode 100644
index 000000000..b80da3774
--- /dev/null
+++ b/constructor/data/construct.schema.json
@@ -0,0 +1,1315 @@
+{
+ "$defs": {
+ "BuildOutputs": {
+ "description": "Allowed keys in 'build_outputs' setting.",
+ "enum": [
+ "hash",
+ "info.json",
+ "licenses",
+ "lockfile",
+ "pkgs_list"
+ ],
+ "title": "BuildOutputs",
+ "type": "string"
+ },
+ "ChannelRemap": {
+ "additionalProperties": false,
+ "properties": {
+ "dest": {
+ "description": "Target channel, after being mapped",
+ "minLength": 1,
+ "title": "Dest",
+ "type": "string"
+ },
+ "src": {
+ "description": "Source channel, before being mapped",
+ "minLength": 1,
+ "title": "Src",
+ "type": "string"
+ }
+ },
+ "required": [
+ "src",
+ "dest"
+ ],
+ "title": "ChannelRemap",
+ "type": "object"
+ },
+ "ExtraEnv": {
+ "additionalProperties": false,
+ "properties": {
+ "channels": {
+ "anyOf": [
+ {
+ "items": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Solve specs using these channels; if not provided, the global value is used. To override inheritance, set it to an empty list.",
+ "title": "Channels"
+ },
+ "channels_remap": {
+ "anyOf": [
+ {
+ "items": {
+ "$ref": "#/$defs/ChannelRemap"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Same as global option, for this env; if not provided, the global value is used. To override inheritance, set it to an empty list.",
+ "title": "Channels Remap"
+ },
+ "environment": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Same as global option, for this environment",
+ "title": "Environment"
+ },
+ "environment_file": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Same as global option, for this environment",
+ "title": "Environment File"
+ },
+ "exclude": {
+ "anyOf": [
+ {
+ "items": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Same as the global option, but for this env. See global option for notes about overrides.",
+ "title": "Exclude"
+ },
+ "menu_packages": {
+ "anyOf": [
+ {
+ "items": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Same as the global option, but for this env. If not provided, global value is _not_ used.",
+ "title": "Menu Packages"
+ },
+ "specs": {
+ "default": [],
+ "description": "Which packages to install in this environment",
+ "items": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "title": "Specs",
+ "type": "array"
+ },
+ "user_requested_specs": {
+ "anyOf": [
+ {
+ "items": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Same as the global option, but for this env. If not provided, global value is _not_ used.",
+ "title": "User Requested Specs"
+ }
+ },
+ "title": "ExtraEnv",
+ "type": "object"
+ },
+ "GuaranteedAlgorithmsEnum": {
+ "enum": [
+ "blake2b",
+ "blake2s",
+ "md5",
+ "sha1",
+ "sha224",
+ "sha256",
+ "sha384",
+ "sha3_224",
+ "sha3_256",
+ "sha3_384",
+ "sha3_512",
+ "sha512",
+ "shake_128",
+ "shake_256"
+ ],
+ "title": "GuaranteedAlgorithmsEnum",
+ "type": "string"
+ },
+ "HashBuildOutput": {
+ "additionalProperties": false,
+ "description": "The hash of the installer files. The output file is designed to work with the `shasum` command and thus has POSIX line endings, including on Windows",
+ "properties": {
+ "hash_": {
+ "$ref": "#/$defs/_HashBuildOutputOptions"
+ }
+ },
+ "required": [
+ "hash_"
+ ],
+ "title": "HashBuildOutput",
+ "type": "object"
+ },
+ "InfoJsonBuildOutput": {
+ "additionalProperties": false,
+ "description": "The internal `info` object, serialized to JSON. Takes no options.",
+ "properties": {
+ "info_json": {
+ "$ref": "#/$defs/_InfoJsonBuildOutputOptions"
+ }
+ },
+ "required": [
+ "info_json"
+ ],
+ "title": "InfoJsonBuildOutput",
+ "type": "object"
+ },
+ "InstallerTypes": {
+ "enum": [
+ "all",
+ "exe",
+ "pkg",
+ "sh"
+ ],
+ "title": "InstallerTypes",
+ "type": "string"
+ },
+ "LicensesBuildOutput": {
+ "additionalProperties": false,
+ "description": "Generate a JSON file with the licensing details of all included packages.",
+ "properties": {
+ "licenses": {
+ "$ref": "#/$defs/_LicensesBuildOutputOptions"
+ }
+ },
+ "required": [
+ "licenses"
+ ],
+ "title": "LicensesBuildOutput",
+ "type": "object"
+ },
+ "LockfileBuildOutput": {
+ "additionalProperties": false,
+ "description": "An `@EXPLICIT` lockfile for a given environment.",
+ "properties": {
+ "lockfile": {
+ "$ref": "#/$defs/_LockfileBuildOutputOptions"
+ }
+ },
+ "required": [
+ "lockfile"
+ ],
+ "title": "LockfileBuildOutput",
+ "type": "object"
+ },
+ "PkgDomains": {
+ "enum": [
+ "enable_anywhere",
+ "enable_currentUserHome",
+ "enable_localSystem"
+ ],
+ "title": "PkgDomains",
+ "type": "string"
+ },
+ "PkgsListBuildOutput": {
+ "additionalProperties": false,
+ "description": "The list of packages contained in a given environment.",
+ "properties": {
+ "pkgs_list": {
+ "$ref": "#/$defs/_PkgsListBuildOutputOptions"
+ }
+ },
+ "required": [
+ "pkgs_list"
+ ],
+ "title": "PkgsListBuildOutput",
+ "type": "object"
+ },
+ "WinSignTools": {
+ "enum": [
+ "azuresigntool",
+ "azuresigntool.exe",
+ "signtool",
+ "signtool.exe"
+ ],
+ "title": "WinSignTools",
+ "type": "string"
+ },
+ "_HashBuildOutputOptions": {
+ "additionalProperties": false,
+ "properties": {
+ "algorithm": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/GuaranteedAlgorithmsEnum"
+ },
+ {
+ "items": {
+ "$ref": "#/$defs/GuaranteedAlgorithmsEnum"
+ },
+ "type": "array"
+ }
+ ],
+ "description": "The hash algorithm. Must be one of `hashlib.algorithms_guaranteed`.",
+ "title": "Algorithm"
+ }
+ },
+ "required": [
+ "algorithm"
+ ],
+ "title": "_HashBuildOutputOptions",
+ "type": "object"
+ },
+ "_InfoJsonBuildOutputOptions": {
+ "additionalProperties": false,
+ "properties": {},
+ "title": "_InfoJsonBuildOutputOptions",
+ "type": "object"
+ },
+ "_LicensesBuildOutputOptions": {
+ "additionalProperties": false,
+ "properties": {
+ "include_text": {
+ "default": false,
+ "description": "Whether to dump the license text in the JSON. If false, only the path will be included.",
+ "title": "Include Text",
+ "type": "boolean"
+ },
+ "text_errors": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "How to handle decoding errors when reading the license text. Only relevant if `include_text` is True. Any str accepted by `open()`'s 'errors' argument is valid. See https://docs.python.org/3/library/functions.html#open.",
+ "title": "Text Errors"
+ }
+ },
+ "title": "_LicensesBuildOutputOptions",
+ "type": "object"
+ },
+ "_LockfileBuildOutputOptions": {
+ "additionalProperties": false,
+ "properties": {
+ "env": {
+ "default": "base",
+ "description": "Name of an environment in 'extra_envs' to be exported.",
+ "minLength": 1,
+ "title": "Env",
+ "type": "string"
+ }
+ },
+ "title": "_LockfileBuildOutputOptions",
+ "type": "object"
+ },
+ "_PkgsListBuildOutputOptions": {
+ "additionalProperties": false,
+ "properties": {
+ "env": {
+ "default": "base",
+ "description": "Name of an environment in 'extra_envs' to be exported.",
+ "minLength": 1,
+ "title": "Env",
+ "type": "string"
+ }
+ },
+ "title": "_PkgsListBuildOutputOptions",
+ "type": "object"
+ }
+ },
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "additionalProperties": false,
+ "description": "Schema for constructor.yaml input files.",
+ "properties": {
+ "$schema": {
+ "default": "https://schemas.conda.org/constructor/v0/construct.schema.json",
+ "description": "JSON Schema URL or path used to validate this input file.",
+ "minLength": 1,
+ "title": "$Schema",
+ "type": "string"
+ },
+ "attempt_hardlinks": {
+ "anyOf": [
+ {
+ "type": "boolean"
+ },
+ {
+ "type": "string"
+ }
+ ],
+ "default": true,
+ "deprecated": true,
+ "description": "_Obsolete_. The current version of constructor relies on the standalone conda executable for its installation behavior. This option is now ignored with a warning.",
+ "title": "Attempt Hardlinks"
+ },
+ "batch_mode": {
+ "default": false,
+ "description": "Only affects `.sh` installers. If `False`, the installer launches an interactive wizard guiding the user through the available options. If `True`, the installer runs automatically as if `-b` was passed.",
+ "title": "Batch Mode",
+ "type": "boolean"
+ },
+ "build_outputs": {
+ "default": [],
+ "description": "Additional artifacts to be produced after building the installer. It expects either a list of strings or single-key dictionaries.\nAllowed strings / keys: `hash`, `info.json`, `licenses`, `lockfile`, `pkgs_list`.",
+ "items": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/BuildOutputs"
+ },
+ {
+ "$ref": "#/$defs/HashBuildOutput"
+ },
+ {
+ "$ref": "#/$defs/InfoJsonBuildOutput"
+ },
+ {
+ "$ref": "#/$defs/PkgsListBuildOutput"
+ },
+ {
+ "$ref": "#/$defs/LockfileBuildOutput"
+ },
+ {
+ "$ref": "#/$defs/LicensesBuildOutput"
+ }
+ ]
+ },
+ "title": "Build Outputs",
+ "type": "array"
+ },
+ "channels": {
+ "default": [],
+ "description": "The conda channels from which packages are retrieved. At least one channel must be supplied, either in `channels` or `channels_remap`.\nSee notes in `channels_remap` for details about local channels.",
+ "items": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "title": "Channels",
+ "type": "array"
+ },
+ "channels_remap": {
+ "default": [],
+ "description": "A list of `src/dest` channel URL pairs. When building the installer, conda will use the `src` channels to solve and fetch the packages. However, the resulting installation will see the packages as coming from the `dest` equivalent. This allows an installer to be built against a different set of channels than will be present when the installer is actually used. Example use:\n```yaml\nchannels_remap:\n - src: file:///tmp/a3/conda-bld # [unix]\n dest: https://repo.anaconda.com/pkgs/main # [unix]\n - src: file:///D:/tmp/a3/conda-bld # [win]\n dest: https://repo.anaconda.com/pkgs/main # [win]\n```\nAt least one channel must be supplied, either in `channels` or `channels_remap`.",
+ "items": {
+ "$ref": "#/$defs/ChannelRemap"
+ },
+ "title": "Channels Remap",
+ "type": "array"
+ },
+ "check_path_length": {
+ "anyOf": [
+ {
+ "type": "boolean"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Check the length of the path where the distribution is installed to ensure nodejs can be installed. Raise a message to request shorter paths (less than 46 character) or enable long paths on windows > 10 (require admin right). Default is True. (Windows only).",
+ "title": "Check Path Length"
+ },
+ "check_path_spaces": {
+ "default": true,
+ "description": "Check if the path where the distribution is installed contains spaces. To allow installations with spaces, change to False. Note that:\n- A recent conda-standalone (>=22.11.1) or equivalent is needed for full support.\n- `conda` cannot be present in the `base` environment",
+ "title": "Check Path Spaces",
+ "type": "boolean"
+ },
+ "company": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Name of the company/entity responsible for the installer.",
+ "title": "Company"
+ },
+ "conclusion_file": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "If `installer_type` is `pkg` on macOS, this message will be shown at the end of the installer upon success. File can be plain text (.txt), rich text (.rtf) or HTML (.html). If both `conclusion_file` and `conclusion_text` are provided, `conclusion_file` takes precedence.\nIf the installer is for Windows, the file type must be nsi.",
+ "title": "Conclusion File"
+ },
+ "conclusion_text": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "A message that will be shown at the end of the installer upon success. The behaviour is slightly different across installer types:\n- PKG: If this key is missing, it defaults to a message about Anaconda Cloud. You can disable it altogether so it defaults to the system message if you set this key to `\"\"` (empty string).\n- EXE: The first line will be used as a title. The following lines will be used as text.",
+ "title": "Conclusion Text"
+ },
+ "conda_channel_alias": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The channel alias that would be assumed for the created installer (only useful if it includes `conda`).",
+ "title": "Conda Channel Alias"
+ },
+ "conda_default_channels": {
+ "default": [],
+ "description": "If this value is provided as well as `write_condarc`, then the channels in this list will be included as the value of the `default_channels:` option in the environment's `.condarc` file. This will have an impact only if `conda` is included in the environmnent.",
+ "items": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "title": "Conda Default Channels",
+ "type": "array"
+ },
+ "condarc": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "If set, a `.condarc` file is written to the base environment containing the contents of this value. The value can either be a string (likely a multi-line string) or a dictionary, which will be converted to a YAML string for writing. _Note:_ if this option is used, then all other options related to the construction of a `.condarc` file (`write_condarc`, `conda_default_channels`, etc.) are ignored.",
+ "title": "Condarc"
+ },
+ "default_image_color": {
+ "default": "blue",
+ "description": "The color of the default images (when not providing explicit image files) used on Windows.",
+ "enum": [
+ "red",
+ "green",
+ "blue",
+ "yellow"
+ ],
+ "title": "Default Image Color",
+ "type": "string"
+ },
+ "default_location_pkg": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Default installation subdirectory in the chosen volume. In PKG installers, default installation locations are configured differently. The user can choose between a \"Just me\" installation (which would result in `~/`) or another volume (which defaults to `/`). If you want a different default, you can add a middle component with this option, let's call it `location`. It would result in these default values: `~//` for \"Just me\", `//` for custom volumes. For example, setting this option to `/Library` in a \"Just me\" installation will give you `~/Library/`. Internally, this is passed to `pkgbuild --install-location`. macOS only.",
+ "title": "Default Location Pkg"
+ },
+ "default_prefix": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Set default install prefix. On Linux, if not provided, the default prefix is `${HOME}/` (or, if `HOME` is not set, `/opt/`). On Windows, this is used only for \"Just Me\" installations; for \"All Users\" installations, use the `default_prefix_all_users` key. If not provided, the default prefix is `%USERPROFILE%\\`. Environment variables will be expanded at install time.",
+ "title": "Default Prefix"
+ },
+ "default_prefix_all_users": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Set default installation prefix for All Users installations. If not provided, the installation prefix will be `%ALLUSERSPROFILE%\\`. Environment variables will be expanded at install time. Windows only.",
+ "title": "Default Prefix All Users"
+ },
+ "default_prefix_domain_user": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Set default installation prefix for domain users. If not provided, the installation prefix for domain users will be `%LOCALAPPDATA%\\`. By default, it is different from the `default_prefix` value to avoid installing the distribution into the roaming profile. Environment variables will be expanded at install time. Windows only.",
+ "title": "Default Prefix Domain User"
+ },
+ "environment": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Name of the environment to construct from. If this option is present, the `specs` argument will be ignored. Using this option allows the user to curate the enviromment interactively using standard `conda` commands, and run constructor with full confidence that the exact environment will be reproduced.",
+ "title": "Environment"
+ },
+ "environment_file": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Path to an environment file (TXT or YAML) to construct from. If this option is present, the `specs` argument will be ignored. Instead, constructor will call conda to create a temporary environment, constructor will build an installer from that, and the temporary environment will be removed. This ensures that constructor is using the precise local conda configuration to discover and install the packages. The created environment MUST include `python`.\nSee notes about the solver in the `specs` field for more information.",
+ "title": "Environment File"
+ },
+ "exclude": {
+ "default": [],
+ "description": "A list of package names to be excluded after the `specs` have been resolved. For example, you can say that `readline` should be excluded, even though it is contained as a result of resolving the specs for `python 2.7`.",
+ "items": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "title": "Exclude",
+ "type": "array"
+ },
+ "extra_envs": {
+ "default": {},
+ "description": "Create more environments in addition to the default `base` provided by `specs`, `environment` or `environment_file`.\nNotes:\n- `ignore_duplicate_files` will always be considered `True` if `extra_envs` is in use.\n- `conda` needs to be present in the `base` environment (via `specs`)\n- If a global `exclude` option is used, it will have an effect on the environments created by `extra_envs` too. For example, if the global environment excludes `tk`, none of the extra environments will have it either. Unlike the global option, an error will not be thrown if the excluded package is not found in the packages required by the extra environment. To override the global `exclude` value, use an empty list `[]`.",
+ "patternProperties": {
+ "^[^/:# ]+$": {
+ "$ref": "#/$defs/ExtraEnv"
+ }
+ },
+ "propertyNames": {
+ "minLength": 1
+ },
+ "title": "Extra Envs",
+ "type": "object"
+ },
+ "extra_files": {
+ "default": [],
+ "description": "Extra, non-packaged files that should be added to the installer. If provided as relative paths, they will be considered relative to the directory where `construct.yaml` is. This setting can be passed as a list of:\n- `str`: each found file will be copied to the root prefix\n- `Mapping[str, str]`: map of path in disk to path in prefix.",
+ "items": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "additionalProperties": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "propertyNames": {
+ "minLength": 1
+ },
+ "type": "object"
+ }
+ ]
+ },
+ "title": "Extra Files",
+ "type": "array"
+ },
+ "header_image": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Like `welcome_image` for Windows, re-sized to 150 x 57 pixels.",
+ "title": "Header Image"
+ },
+ "header_image_text": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "If `header_image` is not provided, use this text when generating the image (Windows only). Defaults to `name`.",
+ "title": "Header Image Text"
+ },
+ "icon_image": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Like `welcome_image` for Windows, re-sized to 256 x 256 pixels.",
+ "title": "Icon Image"
+ },
+ "ignore_duplicate_files": {
+ "default": true,
+ "description": "By default, constructor will warn you when adding packages with duplicate files in them. Setting this option to false will raise an error instead.",
+ "title": "Ignore Duplicate Files",
+ "type": "boolean"
+ },
+ "initialize_by_default": {
+ "anyOf": [
+ {
+ "type": "boolean"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Default value for the option added by `initialize_conda`. The default is true for GUI installers (EXE, PKG) and false for shell installers. The user is able to change the default during interactive installation. NOTE: For Windows, `AddToPath` is disabled when `InstallationType=AllUsers`.\nOnly applies if `initialize_conda` is true.",
+ "title": "Initialize By Default"
+ },
+ "initialize_conda": {
+ "default": true,
+ "description": "Add an option to the installer so the user can choose whether to run `conda init` after the installation (Unix), or to add certain subdirectories of the installation to PATH (Windows). See also `initialize_by_default`.",
+ "title": "Initialize Conda",
+ "type": "boolean"
+ },
+ "install_in_dependency_order": {
+ "anyOf": [
+ {
+ "type": "boolean"
+ },
+ {
+ "type": "string"
+ }
+ ],
+ "default": true,
+ "deprecated": true,
+ "description": "_Obsolete_. The current version of constructor relies on the standalone conda executable for its installation behavior. This option is now ignored with a warning.",
+ "title": "Install In Dependency Order"
+ },
+ "install_path_exists_error_text": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Error message that will be shown if the installation path already exists. You cannot use double quotes or newlines. The placeholder `{CHOSEN_PATH}` is available and set to the destination causing the error. Defaults to:\n> '{CHOSEN_PATH}' already exists. Please, relaunch the installer and choose another location in the Destination Select step.\n(PKG only)",
+ "title": "Install Path Exists Error Text"
+ },
+ "installer_filename": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The filename of the installer being created. If not supplied, a reasonable default will be determined by the `name`, `version`, `platform`, and `installer_type`.",
+ "title": "Installer Filename"
+ },
+ "installer_type": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/InstallerTypes"
+ },
+ {
+ "items": {
+ "$ref": "#/$defs/InstallerTypes"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The type of the installer being created. Possible values are:\n- `sh`: shell-based installer for Linux or macOS\n- `pkg`: macOS GUI installer built with Apple's `pkgbuild`\n- `exe`: Windows GUI installer built with NSIS\nThe default type is `sh` on Linux and macOS, and `exe` on Windows. A special value of `all` builds _both_ `sh` and `pkg` installers on macOS, as well as `sh` on Linux and `exe` on Windows.",
+ "title": "Installer Type"
+ },
+ "keep_pkgs": {
+ "default": false,
+ "description": "If `False`, the package cache in the `pkgs` subdirectory is removed when the installation process is complete. If `True`, this subdirectory and its contents are preserved. If `keep_pkgs` is `False`, Unix `.sh` and Windows `.exe` installers offer a command-line option (`-k` and `/KeepPkgCache`, respectively) to preserve the package cache.",
+ "title": "Keep Pkgs",
+ "type": "boolean"
+ },
+ "license_file": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Path to the license file being displayed by the installer during the install process. It must be plain text (.txt) for shell-based installers. For PKG, .txt, .rtf and .html are supported. On Windows, .txt and .rtf are supported.",
+ "title": "License File"
+ },
+ "menu_packages": {
+ "anyOf": [
+ {
+ "items": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "A list of packages with menu items to be installed. The packages must have necessary metadata in `Menu/.json`. By default, all menu items found in the installation will be created; supplying this list allows a subset to be selected instead. If an empty list is supplied, no shortcuts will be created.\nIf all environments (`extra_envs` included) set `menu_packages` to an empty list, no UI options about shortcuts will be offered to the user.\nNote: This option is not fully implemented when `micromamba` is used as the `--conda-exe` binary. The only accepted value is an empty list (`[]`).",
+ "title": "Menu Packages"
+ },
+ "name": {
+ "description": "Name of the installer. Names may be composed of letters, numbers, underscores, dashes, and periods, but must not begin or end with a dash or period.",
+ "minLength": 1,
+ "pattern": "^[a-zA-Z0-9_]([a-zA-Z0-9._-]*[a-zA-Z0-9_])?$",
+ "title": "Name",
+ "type": "string"
+ },
+ "notarization_identity_name": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "If the pkg installer is going to be signed with `signing_identity_name`, you can also prepare the bundle for notarization. This will use Apple's `codesign` to sign `conda.exe`. For this, you need an \"Application certificate\" (different from the \"Installer certificate\" mentioned above). Common values for this option follow the format `Developer ID Application: Name of the owner (XXXXXX)`.",
+ "title": "Notarization Identity Name"
+ },
+ "nsis_template": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Path to an NSIS template file to use instead of the default template. (Windows only)",
+ "title": "Nsis Template"
+ },
+ "pkg_domains": {
+ "additionalProperties": {
+ "type": "boolean"
+ },
+ "default": {
+ "enable_anywhere": true,
+ "enable_currentUserHome": false
+ },
+ "description": "The domains the package can be installed into. For a detailed explanation, see: https://developer.apple.com/library/archive/documentation/DeveloperTools/Reference/DistributionDefinitionRef/Chapters/Distribution_XML_Ref.html constructor defaults to `enable_anywhere=true` and `enable_currentUserHome=true`. `enable_localSystem` should not be set to true unless `default_location_pkg` is set as well. macOS only.",
+ "propertyNames": {
+ "$ref": "#/$defs/PkgDomains"
+ },
+ "title": "Pkg Domains",
+ "type": "object"
+ },
+ "pkg_name": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Internal identifier for the installer. This is used in the build prefix and will determine part of the default location path. Combine with `default_location_pkg` for more flexibility. If not provided, the value of `name` will be used. (macOS only)",
+ "title": "Pkg Name"
+ },
+ "post_install": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Path to a post-install script. Some notes:\n- For Unix `.sh` installers, the shebang line is respected if present; otherwise, the script is run by the POSIX shell `sh`. Note that the use of a shebang can reduce the portability of the installer. The installation path is available as `${PREFIX}`. Installer metadata is available in the `${INSTALLER_NAME}`, `${INSTALLER_VER}`, `${INSTALLER_PLAT}` environment variables. `${INSTALLER_TYPE}` is set to `SH`. `${INSTALLER_UNATTENDED}` will be `\"1\"` in batch mode (`-b`), `\"0\"` otherwise.\n- For PKG installers, the shebang line is respected if present; otherwise, `bash` is used. The same variables mentioned for `sh` installers are available here. `${INSTALLER_TYPE}` is set to `PKG`. `${INSTALLER_UNATTENDED}` will be `\"1\"` for command line installs, `\"0\"` otherwise.\n- For Windows `.exe` installers, the script must be a `.bat` file. Installation path is available as `%PREFIX%`. Metadata about the installer can be found in the `%INSTALLER_NAME%`, `%INSTALLER_VER%`, `%INSTALLER_PLAT%` environment variables. `%INSTALLER_TYPE%` is set to `EXE`. `%INSTALLER_UNATTENDED%` will be `\"1\"` in silent mode (`/S`), `\"0\"` otherwise.\nIf necessary, you can activate the installed `base` environment like this:\n- Unix: `. \"$PREFIX/etc/profile.d/conda.sh\" && conda activate \"$PREFIX\"`\n- Windows: `call \"%PREFIX%\\Scripts\\activate.bat\"`",
+ "title": "Post Install"
+ },
+ "post_install_desc": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "A description of the purpose of the supplied `post_install` script. If this string is supplied and non-empty, then the Windows and macOS GUI installers will display it along with a checkbox to enable or disable the execution of the script. If this string is not supplied, it is assumed that the script is compulsory and the option to disable it will not be offered.\nThis option has no effect on `SH` installers.",
+ "title": "Post Install Desc"
+ },
+ "post_install_pages": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "items": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Adds extra pages to the installers to be shown after installation.\nFor PKG installers, these can be compiled `installer` plug-ins or directories containing an Xcode project. In the latter case, constructor will try and compile the project file using `xcodebuild`.\nFor Windows, the extra pages must be `.nsi` files. They will be inserted as-is before the conclusion page.",
+ "title": "Post Install Pages"
+ },
+ "pre_install": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Path to a pre-install script, run after the package cache has been set, but before the files are linked to their final locations. As a result, you should only rely on tools known to be available on most systems (e.g. `bash`, `cmd`, etc). See `post_install` for information about available environment variables.",
+ "title": "Pre Install"
+ },
+ "pre_install_desc": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "A description of the purpose of the supplied `pre_install` script. If this string is supplied and non-empty, then the Windows and macOS GUI installers will display it along with a checkbox to enable or disable the execution of the script. If this string is not supplied, it is assumed that the script is compulsory and the option to disable it will not be offered.\nThis option has no effect on `SH` installers.",
+ "title": "Pre Install Desc"
+ },
+ "pre_uninstall": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Path to a pre uninstall script. This is only supported on Windows, and must be a `.bat` file. Installation path is available as `%PREFIX%`. Metadata about the installer can be found in the `%INSTALLER_NAME%`, `%INSTALLER_VER%`, `%INSTALLER_PLAT%` environment variables. `%INSTALLER_TYPE%` is set to `EXE`.",
+ "title": "Pre Uninstall"
+ },
+ "progress_notifications": {
+ "default": false,
+ "description": "Whether to show UI notifications on PKG installers. On large installations, the progress bar reaches ~90% very quickly and stays there for a long time. This might look like the installer froze. This option enables UI notifications so the user receives updates after each command executed by the installer. (macOS only)",
+ "title": "Progress Notifications",
+ "type": "boolean"
+ },
+ "readme_file": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "If `installer_type` is `pkg` on macOS, this message will be shown before the license information, right after the welcome screen. File can be plain text (.txt), rich text (.rtf) or HTML (.html). If both `readme_file` and `readme_text` are provided, `readme_file` takes precedence.",
+ "title": "Readme File"
+ },
+ "readme_text": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "If `installer_type` is `pkg` on macOS, this message will be shown before the license information, right after the welcome screen. If this key is missing, it defaults to a message about Anaconda Cloud. You can disable it altogether if you set this key to `\"\"` (empty string).",
+ "title": "Readme Text"
+ },
+ "register_envs": {
+ "default": true,
+ "description": "Whether to register the environments created by the installer (both `base` and `extra_envs`) in `~/.conda/environments.txt`. Only compatible with conda-standalone >=23.9.",
+ "title": "Register Envs",
+ "type": "boolean"
+ },
+ "register_python": {
+ "default": true,
+ "description": "Whether to offer the user an option to register the installed Python instance as the system's default Python. (Windows only)",
+ "title": "Register Python",
+ "type": "boolean"
+ },
+ "register_python_default": {
+ "anyOf": [
+ {
+ "type": "boolean"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": false,
+ "description": "Default choice for whether to register the installed Python instance as the system's default Python. The user is still able to change this during interactive installation. (Windows only).\nOnly applies if `register_python` is true.",
+ "title": "Register Python Default"
+ },
+ "reverse_domain_identifier": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Unique identifier for this package, formatted with reverse domain notation. This is used internally in the PKG installers to handle future updates and others. If not provided, it will default to `io.continuum`. (MacOS only)",
+ "title": "Reverse Domain Identifier"
+ },
+ "script_env_variables": {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "default": {},
+ "description": "Dictionary of additional environment variables to be made available to the pre_install and post_install scripts, in the form of VAR:VALUE pairs. These environment variables are in addition to those in the `post_install` section above and take precedence in the case of name collisions.\nOn Unix the variable values are automatically single quoted, allowing you to supply strings with spaces, without needing to worry about escaping. As a consequence, string interpolation is disabled: if you need string interpolation, you can apply it in the pre_install/post_install script(s). If you need to include single quotes in your value, you can escape them by replacing each single quote with `'''`.\nOn Windows, single quotes and double quotes are not supported.\nNote that the # (hash) character cannot be used as it denotes yaml comments for all platforms.",
+ "propertyNames": {
+ "minLength": 1
+ },
+ "title": "Script Env Variables",
+ "type": "object"
+ },
+ "signing_certificate": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "On Windows only, set this key to the path of the certificate file to be used with the `windows_signing_tool`.",
+ "title": "Signing Certificate"
+ },
+ "signing_identity_name": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "By default, the MacOS pkg installer isn't signed. If an identity name is specified using this option, it will be used to sign the installer with Apple's `productsign`. Note that you will need to have a certificate (usually an \"Installer certificate\") and the corresponding private key, together called an 'identity', in one of your accessible keychains. Common values for this option follow this format `Developer ID Installer: Name of the owner (XXXXXX)`.",
+ "title": "Signing Identity Name"
+ },
+ "specs": {
+ "anyOf": [
+ {
+ "items": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "minLength": 1,
+ "type": "string"
+ }
+ ],
+ "default": [],
+ "description": "A list of package specifications; e.g. `python 2.7*`, `pyzmq` or `numpy >=1.8`. The specifications are identical in form and purpose to those that would be included in a `conda create --file` command. Packages may also be specified by an exact URL, e.g., `https://repo.anaconda.com/pkgs/main/osx-64/openssl-1.0.2o-h26aff7b_0.tar.bz2`. This key can also take a `str` pointing to a requirements file with the same syntax.\nNote: `constructor` relies on `conda`'s Python API to solve the passed specifications. You can still set the `CONDA_SOLVER` environment variable to override system-wide settings for `constructor`. If you are using `constructor` from a non-`base` environment, make sure the configured solver plugin is also installed in that environment.",
+ "title": "Specs"
+ },
+ "temp_extra_files": {
+ "default": [],
+ "description": "Temporary files that could be referenced in the installation process (i.e. customized `welcome_file` and `conclusion_file`). Should be a list of file paths, relative to the directory where `construct.yaml` is. In Windows, these files will be copied into a temporary folder, the NSIS `$PLUGINSDIR`, during the install process (Windows only).\nSupports the same values as `extra_files`.",
+ "items": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "additionalProperties": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "propertyNames": {
+ "minLength": 1
+ },
+ "type": "object"
+ }
+ ]
+ },
+ "title": "Temp Extra Files",
+ "type": "array"
+ },
+ "transmute_file_type": {
+ "anyOf": [
+ {
+ "const": ".conda",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "File type extension for the files to be transmuted into. If left empty, no transmuting is done.",
+ "title": "Transmute File Type"
+ },
+ "uninstall_name": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Application name in the Windows \"Programs and Features\" control panel. Defaults to `${NAME} ${VERSION} (Python ${PYVERSION} ${ARCH})`.",
+ "title": "Uninstall Name"
+ },
+ "uninstall_with_conda_exe": {
+ "anyOf": [
+ {
+ "type": "boolean"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Use the standalone binary to perform the uninstallation on Windows. Requires conda-standalone 24.11.0 or newer.",
+ "title": "Uninstall With Conda Exe"
+ },
+ "user_requested_specs": {
+ "default": [],
+ "description": "A list of package specifications to be recorded as \"user-requested\" for the initial environment in conda's history file. This information is used by newer versions of conda to better filter its package choices on subsequent installs; for example, if `python=3.6` is included, then conda will always seek versions of packages compatible with Python 3.6. If this option is not provided, it will be set equal to the value of `specs`.",
+ "items": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "title": "User Requested Specs",
+ "type": "array"
+ },
+ "version": {
+ "description": "Version of the installer. Versions may be composed of letters, numbers, underscores, dashes, and periods, but must not begin or end with a dash or period.",
+ "minLength": 1,
+ "pattern": "^[a-zA-Z0-9_]([a-zA-Z0-9._-]*[a-zA-Z0-9_])?$",
+ "title": "Version",
+ "type": "string"
+ },
+ "virtual_specs": {
+ "default": [],
+ "description": "A list of virtual packages that must be satisfied at install time. Virtual packages must start with `__`. For example, `__osx>=11` or `__glibc>=2.24`. These specs are dry-run solved offline by the bundled `--conda-exe` binary. In SH installers, `__glibc>=x.y` and `__osx>=x.y` specs can be checked with Bash only. The detected version can be overriden with environment variables `CONDA_OVERRIDE_GLIBC` and `CONDA_OVERRIDE_OSX`, respectively. In PKG installers, `__osx` specs can be checked natively without the solver being involved as long as only `>=`, `<` or `,` are used.",
+ "items": {
+ "minLength": 3,
+ "pattern": "^__\\S+.*$",
+ "type": "string"
+ },
+ "title": "Virtual Specs",
+ "type": "array"
+ },
+ "welcome_file": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "If `installer_type` is `pkg` on macOS, this message will be shown before the license information, right after the introduction. File can be plain text (.txt), rich text (.rtf) or HTML (.html). If both `welcome_file` and `welcome_text` are provided, `welcome_file` takes precedence.\nIf the installer is for Windows and the welcome file type is nsi, it will use the nsi script to add in extra pages before the installer begins the installation process.",
+ "title": "Welcome File"
+ },
+ "welcome_image": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Path to an image in any common image format (`.png`, `.jpg`, `.tif`, etc.) to be used as the welcome image for the Windows and PKG installers. The image is re-sized to 164 x 314 pixels on Windows and 1227 x 600 on macOS. By default, an image is automatically generated on Windows. On macOS, Anaconda's logo is shown if this key is not provided. If you don't want a background on PKG installers, set this key to `\"\"` (empty string).",
+ "title": "Welcome Image"
+ },
+ "welcome_image_text": {
+ "anyOf": [
+ {
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "If `welcome_image` is not provided, use this text when generating the image (Windows and PKG only). Defaults to `name` on Windows.",
+ "title": "Welcome Image Text"
+ },
+ "welcome_text": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "If `installer_type` is `pkg` on macOS, this message will be shown before the license information, right after the introduction. If this key is missing, it defaults to a message about Anaconda Cloud. You can disable it altogether so it defaults to the system message if you set this key to `\"\"` (empty string).",
+ "title": "Welcome Text"
+ },
+ "windows_signing_tool": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/WinSignTools"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The tool used to sign Windows installers. Must be one of: azuresigntool, signtool. Some tools require `signing_certificate` to be set. Defaults to `signtool` if `signing_certificate` is set. Additional environment variables may need to be used to configure signing. See the documentation for details: https://conda.github.io/constructor/howto/#signing-exe-installers"
+ },
+ "write_condarc": {
+ "default": false,
+ "description": "By default, no `.condarc` file is written. If set, a `.condarc` file is written to the installation directory if there are any channels or `conda_default_channels` is set.",
+ "title": "Write Condarc",
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "name",
+ "version"
+ ],
+ "title": "ConstructorConfiguration",
+ "type": "object"
+}
diff --git a/constructor/main.py b/constructor/main.py
index 8b235b90a..39535bda7 100644
--- a/constructor/main.py
+++ b/constructor/main.py
@@ -10,17 +10,18 @@
"""
import argparse
+import json
import logging
import os
import sys
from os.path import abspath, expanduser, isdir, join
-from textwrap import dedent, indent
+from textwrap import dedent
from . import __version__
from .build_outputs import process_build_outputs
from .conda_interface import SUPPORTED_PLATFORMS, cc_platform
from .conda_interface import VersionOrder as Version
-from .construct import generate_key_info_list, ns_platform
+from .construct import SCHEMA_PATH, ns_platform
from .construct import parse as construct_parse
from .construct import verify as construct_verify
from .fcp import main as fcp_main
@@ -160,13 +161,6 @@ def main_build(
continue
if isinstance(info[key], str):
info[key] = list(yield_lines(join(dir_path, info[key])))
- if key == "virtual_specs":
- for value in info[key]:
- if not value.startswith("__"):
- raise ValueError(
- "'virtual_specs' can only include virtual package names like '__name', "
- f"but you supplied: {value}."
- )
# normalize paths to be copied; if they are relative, they must be to
# construct.yaml's parent (dir_path)
@@ -178,10 +172,9 @@ def main_build(
if isinstance(path, str):
new_extras.append(abspath(join(dir_path, path)))
elif isinstance(path, dict):
- assert len(path) == 1
- orig, dest = next(iter(path.items()))
- orig = abspath(join(dir_path, orig))
- new_extras.append({orig: dest})
+ for orig, dest in path.items():
+ orig = abspath(join(dir_path, orig))
+ new_extras.append({orig: dest})
info[extra_type] = new_extras
for key in "channels", "specs", "exclude", "packages", "menu_packages", "virtual_specs":
@@ -239,14 +232,6 @@ def main_build(
if "pkg" in itypes:
if (domains := info.get("pkg_domains")) is not None:
domains = {key: str(val).lower() for key, val in domains.items()}
- allowed_fields = ["enable_anywhere", "enable_currentUserHome", "enable_localSystem"]
- if any(key not in allowed_fields for key in domains.keys()):
- sys.exit(
- "Error: unrecognized field name(s) for pkg_domains."
- f" Allowed fields are {', '.join(allowed_fields)}"
- )
- if any(val != "true" and val != "false" for val in domains.values()):
- sys.exit("Error: values for pkg_domains must be boolean.")
if str(domains.get("enable_localSystem", "")).lower() == "true" and not info.get(
"default_location_pkg"
):
@@ -350,31 +335,27 @@ def _build_message(self):
Available selectors
-------------------
-
Constructor can use the same Selector enhancement of the YAML format
used in conda-build ('# [selector]'). Available keywords are:
{available_selectors}
"""
)
- available_keys_list = []
- for key, required, key_types, help_msg, plural in generate_key_info_list():
- available_keys_list.append(
- "\n".join(
- [
- key,
- "·" * len(key),
- indent(f"Required: {required}, type{plural}: {key_types}", " "),
- indent(help_msg.strip(), " "),
- "",
- ]
- )
- )
- available_selectors_list = [f"- {sel}" for sel in sorted(ns_platform(sys.platform).keys())]
+ available_keys = [f"> Check full details in {SCHEMA_PATH}", ""]
+ schema = json.loads(SCHEMA_PATH.read_text())
+ for name, prop in schema["properties"].items():
+ if prop.get("deprecated"):
+ continue
+ available_keys.append(f"{name}")
+ available_keys.append("·" * len(name))
+ available_keys.append(prop.get("description", "No description found."))
+ available_keys.append("")
+
+ available_selectors = [f"- {sel}" for sel in sorted(ns_platform(sys.platform).keys())]
return msg.format(
version=__version__,
- available_keys="\n".join(available_keys_list),
- available_selectors="\n".join(available_selectors_list),
+ available_keys="\n".join(available_keys),
+ available_selectors="\n".join(available_selectors),
)
diff --git a/dev/environment.yml b/dev/environment.yml
index 721e3419c..671702206 100644
--- a/dev/environment.yml
+++ b/dev/environment.yml
@@ -8,3 +8,5 @@ dependencies:
- conda-standalone # >=23.11.0
- pillow >=3.1 # [osx or win]
- jinja2
+ - jsonschema >=4
+ - pydantic >=2
diff --git a/docs/source/construct-yaml.md b/docs/source/construct-yaml.md
index 27d449eb9..adbcc0bac 100644
--- a/docs/source/construct-yaml.md
+++ b/docs/source/construct-yaml.md
@@ -34,29 +34,30 @@ are not available here.
> Note: This content is also available in the CLI as `constructor --help-construct`
## Available keys
-### `name`
-_required:_ yes
-_type:_ string
+> This is only a name and description render of the `constructor` JSON Schema.
+> For more details, consider using an online viewer like
+> [json-schema.app](https://json-schema.app/view/%23?url=https%3A%2F%2Fraw.githubusercontent.com%2Fconda%2Fconstructor%2Frefs%2Fheads%2Fmain%2Fconstructor%2Fdata%2Fconstruct.schema.json)
+
+
+### `$schema`
+
+JSON Schema URL or path used to validate this input file.
+
+### `name`
Name of the installer. Names may be composed of letters, numbers,
-underscores, dashes, and periods, but may not begin or end with a
+underscores, dashes, and periods, but must not begin or end with a
dash or period.
### `version`
-_required:_ yes
-_type:_ string
-
Version of the installer. Versions may be composed of letters, numbers,
-underscores, dashes, and periods, but may not begin or end with a
+underscores, dashes, and periods, but must not begin or end with a
dash or period.
### `channels`
-_required:_ no
-_type:_ list
-
The conda channels from which packages are retrieved. At least one channel must
be supplied, either in `channels` or `channels_remap`.
@@ -64,9 +65,6 @@ See notes in `channels_remap` for details about local channels.
### `channels_remap`
-_required:_ no
-_type:_ list
-
A list of `src/dest` channel URL pairs. When building the installer, conda will
use the `src` channels to solve and fetch the packages. However, the resulting
installation will see the packages as coming from the `dest` equivalent.
@@ -78,20 +76,17 @@ channels_remap:
- src: file:///tmp/a3/conda-bld # [unix]
dest: https://repo.anaconda.com/pkgs/main # [unix]
- src: file:///D:/tmp/a3/conda-bld # [win]
- dest: https://repo.anaconda.com/pkgs/main # [unix]
+ dest: https://repo.anaconda.com/pkgs/main # [win]
```
At least one channel must be supplied, either in `channels` or `channels_remap`.
### `specs`
-_required:_ no
-_types:_ list, string
-
A list of package specifications; e.g. `python 2.7*`, `pyzmq` or `numpy >=1.8`.
The specifications are identical in form and purpose to those that would be
included in a `conda create --file` command. Packages may also be specified
-by an exact URL; e.g.,
+by an exact URL, e.g.,
`https://repo.anaconda.com/pkgs/main/osx-64/openssl-1.0.2o-h26aff7b_0.tar.bz2`.
This key can also take a `str` pointing to a requirements file with the same syntax.
@@ -103,21 +98,15 @@ configured solver plugin is also installed in that environment.
### `user_requested_specs`
-_required:_ no
-_types:_ list, string
-
A list of package specifications to be recorded as "user-requested" for the
initial environment in conda's history file. This information is used by newer
versions of conda to better filter its package choices on subsequent installs;
for example, if `python=3.6` is included, then conda will always seek versions
-of packages compatible with Python 3.6. If this is option is not provided, it
+of packages compatible with Python 3.6. If this option is not provided, it
will be set equal to the value of `specs`.
### `virtual_specs`
-_required:_ no
-_type:_ list
-
A list of virtual packages that must be satisfied at install time. Virtual
packages must start with `__`. For example, `__osx>=11` or `__glibc>=2.24`.
These specs are dry-run solved offline by the bundled `--conda-exe` binary.
@@ -129,20 +118,14 @@ involved as long as only `>=`, `<` or `,` are used.
### `exclude`
-_required:_ no
-_type:_ list
-
A list of package names to be excluded after the `specs` have been resolved.
For example, you can say that `readline` should be excluded, even though it
is contained as a result of resolving the specs for `python 2.7`.
### `menu_packages`
-_required:_ no
-_type:_ list
-
A list of packages with menu items to be installed. The packages must have
-necessary metadata in `Menu/.json`). By default, all menu items
+necessary metadata in `Menu/.json`. By default, all menu items
found in the installation will be created; supplying this list allows a
subset to be selected instead. If an empty list is supplied, no shortcuts will
be created.
@@ -155,16 +138,10 @@ the `--conda-exe` binary. The only accepted value is an empty list (`[]`).
### `ignore_duplicate_files`
-_required:_ no
-_type:_ boolean
-
By default, constructor will warn you when adding packages with duplicate
files in them. Setting this option to false will raise an error instead.
-### `install_in_dependency_order`
-
-_required:_ no
-_types:_ boolean, string
+### ~~`install_in_dependency_order`~~
_Obsolete_. The current version of constructor relies on the standalone
conda executable for its installation behavior. This option is now
@@ -172,9 +149,6 @@ ignored with a warning.
### `environment`
-_required:_ no
-_type:_ string
-
Name of the environment to construct from. If this option is present, the
`specs` argument will be ignored. Using this option allows the user to
curate the enviromment interactively using standard `conda` commands, and
@@ -183,33 +157,23 @@ reproduced.
### `environment_file`
-_required:_ no
-_type:_ string
-
Path to an environment file (TXT or YAML) to construct from. If this option
is present, the `specs` argument will be ignored. Instead, constructor will
-call conda to create a temporary environment, constructor will build and
+call conda to create a temporary environment, constructor will build an
installer from that, and the temporary environment will be removed.
This ensures that constructor is using the precise local conda configuration
to discover and install the packages. The created environment MUST include
`python`.
-Read notes about the solver in the `specs` field.
+See notes about the solver in the `specs` field for more information.
### `transmute_file_type`
-_required:_ no
-_type:_ string
-
-File type extension for the files to be transmuted into. Currently supports
-only '.conda'. See conda-package-handling for supported extension names.
+File type extension for the files to be transmuted into.
If left empty, no transmuting is done.
### `conda_default_channels`
-_required:_ no
-_type:_ list
-
If this value is provided as well as `write_condarc`, then the channels
in this list will be included as the value of the `default_channels:`
option in the environment's `.condarc` file. This will have an impact
@@ -217,32 +181,13 @@ only if `conda` is included in the environmnent.
### `conda_channel_alias`
-_required:_ no
-_type:_ string
-
The channel alias that would be assumed for the created installer
-(only useful if it includes conda).
+(only useful if it includes `conda`).
### `extra_envs`
-_required:_ no
-_type:_ dictionary
-
Create more environments in addition to the default `base` provided by `specs`,
-`environment` or `environment_file`. This should be a map of `str` (environment
-name) to a dictionary of options:
-- `specs` (list of str): which packages to install in that environment
-- `environment` (str): same as global option, for this env
-- `environment_file` (str): same as global option, for this env
-- `channels` (list of str): using these channels; if not provided, the global
- value is used. To override inheritance, set it to an empty list.
-- `channels_remap` (list of str): same as global option, for this env;
- if not provided, the global value is used. To override inheritance, set it to
- an empty list.
-- `user_requested_specs` (list of str): same as the global option, but for this env;
- if not provided, global value is _not_ used
-- `menu_packages` (list of str): same as the global option, for this env;
- if not provided, the global value is _not_ used.
+`environment` or `environment_file`.
Notes:
- `ignore_duplicate_files` will always be considered `True` if `extra_envs` is in use.
@@ -255,27 +200,18 @@ Notes:
### `register_envs`
-_required:_ no
-_type:_ boolean
-
Whether to register the environments created by the installer (both `base` and `extra_envs`)
-in `~/.conda/environments.txt`. Only compatible with conda-standalone >=23.9. Defaults to `True`.
+in `~/.conda/environments.txt`. Only compatible with conda-standalone >=23.9.
### `installer_filename`
-_required:_ no
-_type:_ string
-
The filename of the installer being created. If not supplied, a reasonable
-default will determined by the `name`, `version`, platform, and installer type.
+default will be determined by the `name`, `version`, `platform`, and `installer_type`.
### `installer_type`
-_required:_ no
-_types:_ string, list
-
-The type of the installer being created. Possible values are:
-- `sh`: shell-based installer for Linux or macOS;
+The type of the installer being created. Possible values are:
+- `sh`: shell-based installer for Linux or macOS
- `pkg`: macOS GUI installer built with Apple's `pkgbuild`
- `exe`: Windows GUI installer built with NSIS
@@ -283,51 +219,28 @@ The default type is `sh` on Linux and macOS, and `exe` on Windows. A special
value of `all` builds _both_ `sh` and `pkg` installers on macOS, as well
as `sh` on Linux and `exe` on Windows.
-Notes for silent mode `/S` on Windows EXEs:
-- NSIS Silent mode will not print any error message, but will silently abort the installation.
- If needed, [NSIS log-builds][nsis-log] can be used to print to `%PREFIX%\install.log`, which
- can be searched for `::error::` strings. Pre- and post- install scripts will only throw an error
- if the environment variable `NSIS_SCRIPTS_RAISE_ERRORS` is set.
-- The `/D` flag can be used to specify the target location. It must be the last argument in
- the command and should NEVER be quoted, even if it contains spaces. For example:
- `CMD.EXE /C START /WAIT myproject.exe /S /D=C:\path with spaces\my project`.
-
-[nsis-log]: https://nsis.sourceforge.io/Special_Builds
-
### `license_file`
-_required:_ no
-_type:_ string
-
Path to the license file being displayed by the installer during the install
-process. It must be plain text (.txt) for shell-based installers. On PKG,
+process. It must be plain text (.txt) for shell-based installers. For PKG,
.txt, .rtf and .html are supported. On Windows, .txt and .rtf are supported.
### `keep_pkgs`
-_required:_ no
-_type:_ boolean
-
-If `False` (default), the package cache in the `pkgs` subdirectory is removed
+If `False`, the package cache in the `pkgs` subdirectory is removed
when the installation process is complete. If `True`, this subdirectory and
-its contents are preserved. If `keep_pkgs` is `False`, Unix `.sh` and Windows `.msi`
+its contents are preserved. If `keep_pkgs` is `False`, Unix `.sh` and Windows `.exe`
installers offer a command-line option (`-k` and `/KeepPkgCache`, respectively)
to preserve the package cache.
### `batch_mode`
-_required:_ no
-_type:_ boolean
-
-Only affects ``.sh`` installers. If ``False`` (default), the installer launches
+Only affects `.sh` installers. If `False`, the installer launches
an interactive wizard guiding the user through the available options. If
-``True``, the installer runs automatically as if ``-b`` was passed.
+`True`, the installer runs automatically as if `-b` was passed.
### `signing_identity_name`
-_required:_ no
-_type:_ string
-
By default, the MacOS pkg installer isn't signed. If an identity name is specified
using this option, it will be used to sign the installer with Apple's `productsign`.
Note that you will need to have a certificate (usually an "Installer certificate")
@@ -337,9 +250,6 @@ accessible keychains. Common values for this option follow this format
### `notarization_identity_name`
-_required:_ no
-_type:_ string
-
If the pkg installer is going to be signed with `signing_identity_name`, you
can also prepare the bundle for notarization. This will use Apple's `codesign`
to sign `conda.exe`. For this, you need an "Application certificate" (different from the
@@ -348,9 +258,6 @@ to sign `conda.exe`. For this, you need an "Application certificate" (different
### `windows_signing_tool`
-_required:_ no
-_type:_ string
-
The tool used to sign Windows installers. Must be one of: azuresigntool, signtool.
Some tools require `signing_certificate` to be set.
Defaults to `signtool` if `signing_certificate` is set.
@@ -360,16 +267,10 @@ https://conda.github.io/constructor/howto/#signing-exe-installers
### `signing_certificate`
-_required:_ no
-_type:_ string
-
On Windows only, set this key to the path of the certificate file to be used
with the `windows_signing_tool`.
-### `attempt_hardlinks`
-
-_required:_ no
-_types:_ boolean, string
+### ~~`attempt_hardlinks`~~
_Obsolete_. The current version of constructor relies on the standalone
conda executable for its installation behavior. This option is now
@@ -377,17 +278,11 @@ ignored with a warning.
### `write_condarc`
-_required:_ no
-_type:_ boolean
-
By default, no `.condarc` file is written. If set, a `.condarc` file is written to
-the base environment if there are any channels or conda_default_channels is set.
+the installation directory if there are any channels or `conda_default_channels` is set.
### `condarc`
-_required:_ no
-_types:_ dictionary, string
-
If set, a `.condarc` file is written to the base environment containing the contents
of this value. The value can either be a string (likely a multi-line string) or
a dictionary, which will be converted to a YAML string for writing. _Note:_ if this
@@ -396,33 +291,21 @@ file (`write_condarc`, `conda_default_channels`, etc.) are ignored.
### `company`
-_required:_ no
-_type:_ string
-
-Name of the company/entity who is responsible for the installer.
+Name of the company/entity responsible for the installer.
### `reverse_domain_identifier`
-_required:_ no
-_type:_ string
-
Unique identifier for this package, formatted with reverse domain notation. This is
used internally in the PKG installers to handle future updates and others. If not
provided, it will default to `io.continuum`. (MacOS only)
### `uninstall_name`
-_required:_ no
-_type:_ string
-
Application name in the Windows "Programs and Features" control panel.
Defaults to `${NAME} ${VERSION} (Python ${PYVERSION} ${ARCH})`.
### `script_env_variables`
-_required:_ no
-_type:_ dictionary
-
Dictionary of additional environment variables to be made available to
the pre_install and post_install scripts, in the form of VAR:VALUE
pairs. These environment variables are in addition to those in the
@@ -444,9 +327,6 @@ comments for all platforms.
### `pre_install`
-_required:_ no
-_type:_ string
-
Path to a pre-install script, run after the package cache has been set, but
before the files are linked to their final locations. As a result, you should
only rely on tools known to be available on most systems (e.g. `bash`, `cmd`,
@@ -454,12 +334,9 @@ etc). See `post_install` for information about available environment variables.
### `pre_install_desc`
-_required:_ no
-_type:_ string
-
A description of the purpose of the supplied `pre_install` script. If this
string is supplied and non-empty, then the Windows and macOS GUI installers
-will display it along with checkbox to enable or disable the execution of the
+will display it along with a checkbox to enable or disable the execution of the
script. If this string is not supplied, it is assumed that the script
is compulsory and the option to disable it will not be offered.
@@ -467,9 +344,6 @@ This option has no effect on `SH` installers.
### `post_install`
-_required:_ no
-_type:_ string
-
Path to a post-install script. Some notes:
- For Unix `.sh` installers, the shebang line is respected if present;
@@ -491,17 +365,14 @@ Path to a post-install script. Some notes:
If necessary, you can activate the installed `base` environment like this:
-- Unix: `source "$PREFIX/etc/profile.d/conda.sh" && conda activate "$PREFIX"`
+- Unix: `. "$PREFIX/etc/profile.d/conda.sh" && conda activate "$PREFIX"`
- Windows: `call "%PREFIX%\Scripts\activate.bat"`
### `post_install_desc`
-_required:_ no
-_type:_ string
-
A description of the purpose of the supplied `post_install` script. If this
string is supplied and non-empty, then the Windows and macOS GUI installers
-will display it along with checkbox to enable or disable the execution of the
+will display it along with a checkbox to enable or disable the execution of the
script. If this string is not supplied, it is assumed that the script
is compulsory and the option to disable it will not be offered.
@@ -509,10 +380,7 @@ This option has no effect on `SH` installers.
### `pre_uninstall`
-_required:_ no
-_type:_ string
-
-Path to a pre uninstall script. This is only supported for on Windows,
+Path to a pre uninstall script. This is only supported on Windows,
and must be a `.bat` file. Installation path is available as `%PREFIX%`.
Metadata about the installer can be found in the `%INSTALLER_NAME%`,
`%INSTALLER_VER%`, `%INSTALLER_PLAT%` environment variables.
@@ -520,42 +388,29 @@ Metadata about the installer can be found in the `%INSTALLER_NAME%`,
### `default_prefix`
-_required:_ no
-_type:_ string
-
Set default install prefix. On Linux, if not provided, the default prefix
is `${HOME}/` (or, if `HOME` is not set, `/opt/`). On Windows,
-this is used only for "Just Me" installation; for "All Users" installation,
+this is used only for "Just Me" installations; for "All Users" installations,
use the `default_prefix_all_users` key. If not provided, the default prefix
is `%USERPROFILE%\`. Environment variables will be expanded at
-installation time.
+install time.
### `default_prefix_domain_user`
-_required:_ no
-_type:_ string
-
-Set default installation prefix for domain user. If not provided, the
-installation prefix for domain user will be `%LOCALAPPDATA%\`.
+Set default installation prefix for domain users. If not provided, the
+installation prefix for domain users will be `%LOCALAPPDATA%\`.
By default, it is different from the `default_prefix` value to avoid installing
-the distribution in the roaming profile. Environment variables will be expanded
-at installation time. Windows only.
+the distribution into the roaming profile. Environment variables will be expanded
+at install time. Windows only.
### `default_prefix_all_users`
-_required:_ no
-_type:_ string
-
-Set default installation prefix for All Users installation. If not provided,
-the installation prefix for all users installation will be
-`%ALLUSERSPROFILE%\`. Environment variables will be expanded at installation
-time. Windows only.
+Set default installation prefix for All Users installations. If not provided,
+the installation prefix will be `%ALLUSERSPROFILE%\`.
+Environment variables will be expanded at install time. Windows only.
### `default_location_pkg`
-_required:_ no
-_type:_ string
-
Default installation subdirectory in the chosen volume. In PKG installers,
default installation locations are configured differently. The user can choose
between a "Just me" installation (which would result in `~/`) or another
@@ -569,9 +424,6 @@ macOS only.
### `pkg_domains`
-_required:_ no
-_type:_ dictionary
-
The domains the package can be installed into. For a detailed explanation, see:
https://developer.apple.com/library/archive/documentation/DeveloperTools/Reference/DistributionDefinitionRef/Chapters/Distribution_XML_Ref.html
constructor defaults to `enable_anywhere=true` and `enable_currentUserHome=true`.
@@ -580,32 +432,23 @@ macOS only.
### `pkg_name`
-_required:_ no
-_type:_ string
-
Internal identifier for the installer. This is used in the build prefix and will
determine part of the default location path. Combine with `default_location_pkg`
-for more flexibility. If not provided, the value of `name` will be used. (MacOS only)
+for more flexibility. If not provided, the value of `name` will be used. (macOS only)
### `install_path_exists_error_text`
-_required:_ no
-_type:_ string
-
Error message that will be shown if the installation path already exists.
You cannot use double quotes or newlines. The placeholder `{CHOSEN_PATH}` is
available and set to the destination causing the error. Defaults to:
> '{CHOSEN_PATH}' already exists. Please, relaunch the installer and
-> choose another location in the Destination Select step.
+choose another location in the Destination Select step.
-(MacOS only)
+(PKG only)
### `progress_notifications`
-_required:_ no
-_type:_ boolean
-
Whether to show UI notifications on PKG installers. On large installations,
the progress bar reaches ~90% very quickly and stays there for a long time.
This might look like the installer froze. This option enables UI notifications
@@ -614,179 +457,117 @@ so the user receives updates after each command executed by the installer.
### `welcome_image`
-_required:_ no
-_type:_ string
-
Path to an image in any common image format (`.png`, `.jpg`, `.tif`, etc.)
to be used as the welcome image for the Windows and PKG installers.
-The image is re-sized to 164 x 314 pixels on Windows and 1227 x 600 on Macos.
-By default, an image is automatically generated on Windows. On MacOS, Anaconda's
+The image is re-sized to 164 x 314 pixels on Windows and 1227 x 600 on macOS.
+By default, an image is automatically generated on Windows. On macOS, Anaconda's
logo is shown if this key is not provided. If you don't want a background on
PKG installers, set this key to `""` (empty string).
### `header_image`
-_required:_ no
-_type:_ string
-
Like `welcome_image` for Windows, re-sized to 150 x 57 pixels.
### `icon_image`
-_required:_ no
-_type:_ string
-
Like `welcome_image` for Windows, re-sized to 256 x 256 pixels.
### `default_image_color`
-_required:_ no
-_type:_ string
-
The color of the default images (when not providing explicit image files)
-used on Windows. Possible values are `red`, `green`, `blue`, `yellow`.
-The default is `blue`.
+used on Windows.
### `welcome_image_text`
-_required:_ no
-_type:_ string
-
If `welcome_image` is not provided, use this text when generating the image
(Windows and PKG only). Defaults to `name` on Windows.
### `header_image_text`
-_required:_ no
-_type:_ string
-
If `header_image` is not provided, use this text when generating the image
(Windows only). Defaults to `name`.
### `initialize_conda`
-_required:_ no
-_type:_ boolean
-
Add an option to the installer so the user can choose whether to run `conda init`
-after the install. See also `initialize_by_default`.
+after the installation (Unix), or to add certain subdirectories of the installation
+to PATH (Windows). See also `initialize_by_default`.
### `initialize_by_default`
-_required:_ no
-_type:_ boolean
-
-Whether to add the installation to the PATH environment variable. The default
-is true for GUI installers (msi, pkg) and False for shell installers. The user
+Default value for the option added by `initialize_conda`. The default
+is true for GUI installers (EXE, PKG) and false for shell installers. The user
is able to change the default during interactive installation. NOTE: For Windows,
`AddToPath` is disabled when `InstallationType=AllUsers`.
-### `register_python`
+Only applies if `initialize_conda` is true.
-_required:_ no
-_type:_ boolean
+### `register_python`
Whether to offer the user an option to register the installed Python instance as the
system's default Python. (Windows only)
### `register_python_default`
-_required:_ no
-_type:_ boolean
-
Default choice for whether to register the installed Python instance as the
system's default Python. The user is still able to change this during
interactive installation. (Windows only).
-### `check_path_length`
+Only applies if `register_python` is true.
-_required:_ no
-_type:_ boolean
+### `check_path_length`
Check the length of the path where the distribution is installed to ensure nodejs
-can be installed. Raise a message to request shorter path (less than 46 character)
-or enable long path on windows > 10 (require admin right). Default is True. (Windows only).
-
-Read notes about the particularities of Windows silent mode `/S` in the
-`installer_type` documentation.
+can be installed. Raise a message to request shorter paths (less than 46 character)
+or enable long paths on windows > 10 (require admin right). Default is True. (Windows only).
### `check_path_spaces`
-_required:_ no
-_type:_ boolean
-
-Check if the path where the distribution is installed contains spaces. Default is True.
+Check if the path where the distribution is installed contains spaces.
To allow installations with spaces, change to False. Note that:
- A recent conda-standalone (>=22.11.1) or equivalent is needed for full support.
- `conda` cannot be present in the `base` environment
-Read notes about the particularities of Windows silent mode `/S` in the
-`installer_type` documentation.
-
### `nsis_template`
-_required:_ no
-_type:_ string
-
-If `nsis_template` is not provided, constructor uses its default
-NSIS template. For more complete customization for the installation experience,
-provide an NSIS template file. (Windows only).
+Path to an NSIS template file to use instead of the default template. (Windows only)
### `welcome_file`
-_required:_ no
-_type:_ string
-
-If `installer_type` is `pkg` on MacOS, this message will be
+If `installer_type` is `pkg` on macOS, this message will be
shown before the license information, right after the introduction.
File can be plain text (.txt), rich text (.rtf) or HTML (.html). If
both `welcome_file` and `welcome_text` are provided, `welcome_file` takes precedence.
-(MacOS only).
-If the installer is for windows and welcome file type is nsi,
+If the installer is for Windows and the welcome file type is nsi,
it will use the nsi script to add in extra pages before the installer
begins the installation process.
### `welcome_text`
-_required:_ no
-_type:_ string
-
-If `installer_type` is `pkg` on MacOS, this message will be
+If `installer_type` is `pkg` on macOS, this message will be
shown before the license information, right after the introduction.
If this key is missing, it defaults to a message about Anaconda Cloud.
You can disable it altogether so it defaults to the system message
if you set this key to `""` (empty string).
-(MacOS only).
### `readme_file`
-_required:_ no
-_type:_ string
-
-If `installer_type` is `pkg` on MacOS, this message will be
+If `installer_type` is `pkg` on macOS, this message will be
shown before the license information, right after the welcome screen.
File can be plain text (.txt), rich text (.rtf) or HTML (.html). If
both `readme_file` and `readme_text` are provided, `readme_file` takes precedence.
-(MacOS only).
### `readme_text`
-_required:_ no
-_type:_ string
-
-If `installer_type` is `pkg` on MacOS, this message will be
+If `installer_type` is `pkg` on macOS, this message will be
shown before the license information, right after the welcome screen.
If this key is missing, it defaults to a message about Anaconda Cloud.
You can disable it altogether if you set this key to `""` (empty string).
-(MacOS only).
### `post_install_pages`
-_required:_ no
-_types:_ list, string
-
Adds extra pages to the installers to be shown after installation.
For PKG installers, these can be compiled `installer` plug-ins or
@@ -798,35 +579,25 @@ They will be inserted as-is before the conclusion page.
### `conclusion_file`
-_required:_ no
-_type:_ string
-
-If `installer_type` is `pkg` on MacOS, this message will be
+If `installer_type` is `pkg` on macOS, this message will be
shown at the end of the installer upon success. File can be
plain text (.txt), rich text (.rtf) or HTML (.html). If both
`conclusion_file` and `conclusion_text` are provided,
-`conclusion_file` takes precedence. (MacOS only).
+`conclusion_file` takes precedence.
If the installer is for Windows, the file type must be nsi.
### `conclusion_text`
-_required:_ no
-_type:_ string
-
A message that will be shown at the end of the installer upon success.
The behaviour is slightly different across installer types:
- PKG: If this key is missing, it defaults to a message about Anaconda Cloud.
You can disable it altogether so it defaults to the system message if you set this
key to `""` (empty string).
- EXE: The first line will be used as a title. The following lines will be used as text.
-(macOS PKG and Windows only).
### `extra_files`
-_required:_ no
-_type:_ list
-
Extra, non-packaged files that should be added to the installer. If provided as relative
paths, they will be considered relative to the directory where `construct.yaml` is.
This setting can be passed as a list of:
@@ -835,47 +606,24 @@ This setting can be passed as a list of:
### `temp_extra_files`
-_required:_ no
-_type:_ list
-
Temporary files that could be referenced in the installation process (i.e. customized
-`welcome_file` and `conclusion_file` (see above)) . Should be a list of
+`welcome_file` and `conclusion_file`). Should be a list of
file paths, relative to the directory where `construct.yaml` is. In Windows, these
files will be copied into a temporary folder, the NSIS `$PLUGINSDIR`, during
-install process (Windows only).
+the install process (Windows only).
Supports the same values as `extra_files`.
### `build_outputs`
-_required:_ no
-_type:_ list
-
Additional artifacts to be produced after building the installer.
-It expects either a list of strings or single-key dictionaries:
-Allowed keys are:
-- `hash`: The hash of the installer files. The output file is designed to work with the `shasum`
- command and thus has POSIX line endings, including on Windows. Options:
- - `algorithm` (str or list): The hash algorithm. Must be among `hashlib`'s available algorithms:
- https://docs.python.org/3/library/hashlib.html#hashlib.algorithms_available
-- `info.json`: The internal `info` object, serialized to JSON. Takes no options.
-- `pkgs_list`: The list of packages contained in a given environment. Options:
- - `env` (optional, default=`base`): Name of an environment in `extra_envs` to export.
-- `lockfile`: An `@EXPLICIT` lockfile for a given environment. Options:
- - `env` (optional, default=`base`): Name of an environment in `extra_envs` to export.
-- `licenses`: Generate a JSON file with the licensing details of all included packages. Options:
- - `include_text` (optional bool, default=`False`): Whether to dump the license text in the JSON.
- If false, only the path will be included.
- - `text_errors` (optional str, default=`None`): How to handle decoding errors when reading the
- license text. Only relevant if include_text is True. Any str accepted by open()'s 'errors'
- argument is valid. See https://docs.python.org/3/library/functions.html#open.
+It expects either a list of strings or single-key dictionaries.
-### `uninstall_with_conda_exe`
+Allowed strings / keys: `hash`, `info.json`, `licenses`, `lockfile`, `pkgs_list`.
-_required:_ no
-_type:_ boolean
+### `uninstall_with_conda_exe`
-Use the standalone binary to perform the uninstallation.
+Use the standalone binary to perform the uninstallation on Windows.
Requires conda-standalone 24.11.0 or newer.
@@ -897,7 +645,8 @@ Requires conda-standalone 24.11.0 or newer.
- `x86_64`
## Available Platforms
-Specify which platform (`CONDA_SUBDIR`) to build for via the `--platform` argument. If provided, this argument must be formated as `-`, e.g.:
+Specify which platform (`CONDA_SUBDIR`) to build for via the `--platform` argument.
+If provided, this argument must be formated as `-`, e.g.:
- `linux-64`
- `linux-aarch64`
- `linux-ppc64le`
diff --git a/examples/azure_signtool/construct.yaml b/examples/azure_signtool/construct.yaml
index 37b3c1744..f40c2efa3 100644
--- a/examples/azure_signtool/construct.yaml
+++ b/examples/azure_signtool/construct.yaml
@@ -1,3 +1,6 @@
+# yaml-language-server: $schema=../../constructor/data/construct.schema.json
+"$schema": "../../constructor/data/construct.schema.json"
+
name: Signed_AzureSignTool
version: X
installer_type: exe
diff --git a/examples/custom_nsis_template/construct.yaml b/examples/custom_nsis_template/construct.yaml
index 59bf7f503..4b8eab0b4 100644
--- a/examples/custom_nsis_template/construct.yaml
+++ b/examples/custom_nsis_template/construct.yaml
@@ -1,3 +1,6 @@
+# yaml-language-server: $schema=../../constructor/data/construct.schema.json
+"$schema": "../../constructor/data/construct.schema.json"
+
name: custom
version: X
ignore_duplicate_files: True
diff --git a/examples/customize_controls/construct.yaml b/examples/customize_controls/construct.yaml
index aae91d0fa..074c6e8de 100644
--- a/examples/customize_controls/construct.yaml
+++ b/examples/customize_controls/construct.yaml
@@ -1,3 +1,6 @@
+# yaml-language-server: $schema=../../constructor/data/construct.schema.json
+"$schema": "../../constructor/data/construct.schema.json"
+
name: NoCondaOptions
version: X
installer_type: all
diff --git a/examples/customized_welcome_conclusion/construct.yaml b/examples/customized_welcome_conclusion/construct.yaml
index 6a4de2591..79f55f943 100644
--- a/examples/customized_welcome_conclusion/construct.yaml
+++ b/examples/customized_welcome_conclusion/construct.yaml
@@ -1,3 +1,6 @@
+# yaml-language-server: $schema=../../constructor/data/construct.schema.json
+"$schema": "../../constructor/data/construct.schema.json"
+
name: CustomizedWelcomeConclusion
version: X
installer_type: all
diff --git a/examples/exe_extra_pages/construct.yaml b/examples/exe_extra_pages/construct.yaml
index a7987b4e9..862cb1d9b 100644
--- a/examples/exe_extra_pages/construct.yaml
+++ b/examples/exe_extra_pages/construct.yaml
@@ -1,3 +1,6 @@
+# yaml-language-server: $schema=../../constructor/data/construct.schema.json
+"$schema": "../../constructor/data/construct.schema.json"
+
{% if os.environ.get("POST_INSTALL_PAGES_LIST") %}
{% set name = "extraPages" %}
{% else %}
diff --git a/examples/extra_envs/construct.yaml b/examples/extra_envs/construct.yaml
index b839b9239..aedaf28ff 100644
--- a/examples/extra_envs/construct.yaml
+++ b/examples/extra_envs/construct.yaml
@@ -1,3 +1,6 @@
+# yaml-language-server: $schema=../../constructor/data/construct.schema.json
+"$schema": "../../constructor/data/construct.schema.json"
+
name: ExtraEnvs
version: X
installer_type: all
diff --git a/examples/extra_files/construct.yaml b/examples/extra_files/construct.yaml
index 1d248235e..0bcbd2b6d 100644
--- a/examples/extra_files/construct.yaml
+++ b/examples/extra_files/construct.yaml
@@ -1,3 +1,6 @@
+# yaml-language-server: $schema=../../constructor/data/construct.schema.json
+"$schema": "../../constructor/data/construct.schema.json"
+
name: ExtraFiles
version: X
installer_type: all
@@ -8,7 +11,9 @@ channels:
specs:
- python
extra_files:
- - something.txt: more_data/README.md
- something2.txt
+ - something.txt: more_data/README.md
+ - something2.txt: more_data/something2.md
+ something.txt: more_data/something.md
post_install: test_install.sh # [unix]
post_install: test_install.bat # [win]
diff --git a/examples/from_env_txt/construct.yaml b/examples/from_env_txt/construct.yaml
index 5a6f0aa2f..ee8412dc7 100644
--- a/examples/from_env_txt/construct.yaml
+++ b/examples/from_env_txt/construct.yaml
@@ -1,3 +1,6 @@
+# yaml-language-server: $schema=../../constructor/data/construct.schema.json
+"$schema": "../../constructor/data/construct.schema.json"
+
name: EnvironmentTXT
version: X
installer_type: all
diff --git a/examples/from_env_yaml/construct.yaml b/examples/from_env_yaml/construct.yaml
index 7c792e204..d86bdeafb 100644
--- a/examples/from_env_yaml/construct.yaml
+++ b/examples/from_env_yaml/construct.yaml
@@ -1,3 +1,6 @@
+# yaml-language-server: $schema=../../constructor/data/construct.schema.json
+"$schema": "../../constructor/data/construct.schema.json"
+
name: EnvironmentYAML
version: X
installer_type: all
diff --git a/examples/from_existing_env/construct.yaml b/examples/from_existing_env/construct.yaml
index 33fe9fc32..e60d00945 100644
--- a/examples/from_existing_env/construct.yaml
+++ b/examples/from_existing_env/construct.yaml
@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=../../constructor/data/construct.schema.json
+"$schema": "../../constructor/data/construct.schema.json"
name: Existing
version: X
installer_type: all
diff --git a/examples/from_explicit/construct.yaml b/examples/from_explicit/construct.yaml
index 67e3f6e46..9137fa8f7 100644
--- a/examples/from_explicit/construct.yaml
+++ b/examples/from_explicit/construct.yaml
@@ -1,3 +1,6 @@
+# yaml-language-server: $schema=../../constructor/data/construct.schema.json
+"$schema": "../../constructor/data/construct.schema.json"
+
name: Explicit
version: X
installer_type: all
diff --git a/examples/grin/construct.yaml b/examples/grin/construct.yaml
index 2bb45f6aa..553ffa45e 100644
--- a/examples/grin/construct.yaml
+++ b/examples/grin/construct.yaml
@@ -1,3 +1,6 @@
+# yaml-language-server: $schema=../../constructor/data/construct.schema.json
+"$schema": "../../constructor/data/construct.schema.json"
+
# name and version (required)
name: test
version: 3
diff --git a/examples/jetsonconda/construct.yaml b/examples/jetsonconda/construct.yaml
index d9eb5f9a4..ee1b5b49f 100644
--- a/examples/jetsonconda/construct.yaml
+++ b/examples/jetsonconda/construct.yaml
@@ -1,3 +1,6 @@
+# yaml-language-server: $schema=../../constructor/data/construct.schema.json
+"$schema": "../../constructor/data/construct.schema.json"
+
name: JetsonConda
version: 0.1
diff --git a/examples/miniconda/construct.yaml b/examples/miniconda/construct.yaml
index 8fe996cd6..7c5dad48b 100644
--- a/examples/miniconda/construct.yaml
+++ b/examples/miniconda/construct.yaml
@@ -1,3 +1,6 @@
+# yaml-language-server: $schema=../../constructor/data/construct.schema.json
+"$schema": "../../constructor/data/construct.schema.json"
+
name: MinicondaX
version: X
installer_type: all
diff --git a/examples/miniforge-mamba2/construct.yaml b/examples/miniforge-mamba2/construct.yaml
index 24eb4a512..98feefec3 100644
--- a/examples/miniforge-mamba2/construct.yaml
+++ b/examples/miniforge-mamba2/construct.yaml
@@ -1,5 +1,8 @@
+# yaml-language-server: $schema=../../constructor/data/construct.schema.json
+"$schema": "../../constructor/data/construct.schema.json"
+
name: Miniforge3-mamba2
-version: 25.0.0-2
+version: 25.1.1-0
company: conda-forge
license_file: EULA.txt
@@ -12,8 +15,8 @@ transmute_file_type: .conda
specs:
- python 3.12.*
- - conda 24.11.2
- - mamba 2.0.5
+ - conda 25.1.1
+ - mamba 2.0.8
- pip
- miniforge_console_shortcut 1.* # [win]
diff --git a/examples/miniforge-mamba2/test_install.sh b/examples/miniforge-mamba2/test_install.sh
index 701049721..2ffe21b61 100644
--- a/examples/miniforge-mamba2/test_install.sh
+++ b/examples/miniforge-mamba2/test_install.sh
@@ -19,7 +19,7 @@ echo "+ Testing conda channels"
conda config --show --json | python -c "import sys, json; info = json.loads(sys.stdin.read()); assert 'conda-forge' in info['channels'], info"
echo " OK"
-EXPECTED_MAMBA_VERSION="2.0.5"
+EXPECTED_MAMBA_VERSION="2.0.8"
# Get versions with conda
MAMBA_VERSION=$(conda list "^mamba$" --json | python -c "import sys, json; info = json.loads(sys.stdin.read()); print(info[0]['version'])")
diff --git a/examples/miniforge/construct.yaml b/examples/miniforge/construct.yaml
index 040f111a0..eb894cc91 100644
--- a/examples/miniforge/construct.yaml
+++ b/examples/miniforge/construct.yaml
@@ -1,3 +1,6 @@
+# yaml-language-server: $schema=../../constructor/data/construct.schema.json
+"$schema": "../../constructor/data/construct.schema.json"
+
name: Miniforge3
version: 25.0.0-1
company: conda-forge
diff --git a/examples/newchan/construct.yaml b/examples/newchan/construct.yaml
index 05a1b668b..bd32546ed 100644
--- a/examples/newchan/construct.yaml
+++ b/examples/newchan/construct.yaml
@@ -1,3 +1,6 @@
+# yaml-language-server: $schema=../../constructor/data/construct.schema.json
+"$schema": "../../constructor/data/construct.schema.json"
+
name: Funnychan
version: 2.5.5
diff --git a/examples/noconda/constructor_input.yaml b/examples/noconda/constructor_input.yaml
index 5a522cea2..5e3fa6fd3 100644
--- a/examples/noconda/constructor_input.yaml
+++ b/examples/noconda/constructor_input.yaml
@@ -1,3 +1,6 @@
+# yaml-language-server: $schema=../../constructor/data/construct.schema.json
+"$schema": "../../constructor/data/construct.schema.json"
+
name: NoConda
version: X
installer_type: all
diff --git a/examples/osxpkg/construct.yaml b/examples/osxpkg/construct.yaml
index b749fa6ec..d9ddae385 100644
--- a/examples/osxpkg/construct.yaml
+++ b/examples/osxpkg/construct.yaml
@@ -1,3 +1,6 @@
+# yaml-language-server: $schema=../../constructor/data/construct.schema.json
+"$schema": "../../constructor/data/construct.schema.json"
+
name: osxpkgtest
version: 1.2.3
diff --git a/examples/osxpkg_extra_pages/construct.yaml b/examples/osxpkg_extra_pages/construct.yaml
index 36f47f00d..201fe8969 100644
--- a/examples/osxpkg_extra_pages/construct.yaml
+++ b/examples/osxpkg_extra_pages/construct.yaml
@@ -1,3 +1,6 @@
+# yaml-language-server: $schema=../../constructor/data/construct.schema.json
+"$schema": "../../constructor/data/construct.schema.json"
+
name: osxpkgtest
version: 1.2.3
diff --git a/examples/register_envs/construct.yaml b/examples/register_envs/construct.yaml
index 5db921d2f..b55eae9ea 100644
--- a/examples/register_envs/construct.yaml
+++ b/examples/register_envs/construct.yaml
@@ -1,3 +1,6 @@
+# yaml-language-server: $schema=../../constructor/data/construct.schema.json
+"$schema": "../../constructor/data/construct.schema.json"
+
name: RegisterEnvs
version: X
installer_type: all
diff --git a/examples/regressions/construct.yaml b/examples/regressions/construct.yaml
index ceda1fd05..b4f7a6824 100644
--- a/examples/regressions/construct.yaml
+++ b/examples/regressions/construct.yaml
@@ -1,3 +1,6 @@
+# yaml-language-server: $schema=../../constructor/data/construct.schema.json
+"$schema": "../../constructor/data/construct.schema.json"
+
name: regressions
version: 0.0.1
diff --git a/examples/scripts/construct.yaml b/examples/scripts/construct.yaml
index e57bdffa0..935b1f40b 100644
--- a/examples/scripts/construct.yaml
+++ b/examples/scripts/construct.yaml
@@ -1,3 +1,6 @@
+# yaml-language-server: $schema=../../constructor/data/construct.schema.json
+"$schema": "../../constructor/data/construct.schema.json"
+
name: Scripts
version: X
installer_type: all
diff --git a/examples/shortcuts/construct.yaml b/examples/shortcuts/construct.yaml
index e22d46d97..b237e83c2 100644
--- a/examples/shortcuts/construct.yaml
+++ b/examples/shortcuts/construct.yaml
@@ -1,3 +1,6 @@
+# yaml-language-server: $schema=../../constructor/data/construct.schema.json
+"$schema": "../../constructor/data/construct.schema.json"
+
name: MinicondaWithShortcuts
version: X
installer_type: all
diff --git a/examples/signing/construct.yaml b/examples/signing/construct.yaml
index 5deb48f42..06ce44d00 100644
--- a/examples/signing/construct.yaml
+++ b/examples/signing/construct.yaml
@@ -1,3 +1,6 @@
+# yaml-language-server: $schema=../../constructor/data/construct.schema.json
+"$schema": "../../constructor/data/construct.schema.json"
+
name: Signed
version: X
installer_type: all
diff --git a/examples/use_channel_remap/construct.yaml b/examples/use_channel_remap/construct.yaml
index 2fd86f0ff..bf4aa7f2b 100644
--- a/examples/use_channel_remap/construct.yaml
+++ b/examples/use_channel_remap/construct.yaml
@@ -1,3 +1,6 @@
+# yaml-language-server: $schema=../../constructor/data/construct.schema.json
+"$schema": "../../constructor/data/construct.schema.json"
+
name: use_channel_remap
version: 0.0.1
diff --git a/examples/virtual_specs_failed/construct.yaml b/examples/virtual_specs_failed/construct.yaml
index 0b8eae288..f3b554872 100644
--- a/examples/virtual_specs_failed/construct.yaml
+++ b/examples/virtual_specs_failed/construct.yaml
@@ -1,3 +1,6 @@
+# yaml-language-server: $schema=../../constructor/data/construct.schema.json
+"$schema": "../../constructor/data/construct.schema.json"
+
name: virtual_specs_failed
version: 0.0.1
diff --git a/examples/virtual_specs_ok/construct.yaml b/examples/virtual_specs_ok/construct.yaml
index e92e61f49..41635eefc 100644
--- a/examples/virtual_specs_ok/construct.yaml
+++ b/examples/virtual_specs_ok/construct.yaml
@@ -1,3 +1,6 @@
+# yaml-language-server: $schema=../../constructor/data/construct.schema.json
+"$schema": "../../constructor/data/construct.schema.json"
+
name: virtual_specs_ok
version: 0.0.1
diff --git a/news/943-schema b/news/943-schema
new file mode 100644
index 000000000..ca9e4edf7
--- /dev/null
+++ b/news/943-schema
@@ -0,0 +1,19 @@
+### Enhancements
+
+* Add JSON Schema for `construct.yml`, defined with a Pydantic model (not used at runtime). (#943)
+
+### Bug fixes
+
+*
+
+### Deprecations
+
+* Remove deprecated `constructor.construct.generate_docs()` function. Use `scripts/make_docs.py` instead. (#943)
+
+### Docs
+
+* Remove inaccurate typing information from the `construct.yml` fields documentation. Full and accurate details are now available in the JSON Schema. (#943)
+
+### Other
+
+*
diff --git a/pyproject.toml b/pyproject.toml
index 8f89088ac..e85b969b6 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -16,8 +16,12 @@ dependencies = [
"ruamel.yaml >=0.11.14,<0.19",
"pillow >=3.1 ; platform_system=='Windows' or platform_system=='Darwin'",
"jinja2",
+ "jsonschema >=4"
]
+[project.optional-dependencies]
+schema = ["pydantic >=2"]
+
[project.scripts]
constructor = "constructor.main:main"
diff --git a/recipe/meta.yaml b/recipe/meta.yaml
index 1f9c7a32c..77e4464ce 100644
--- a/recipe/meta.yaml
+++ b/recipe/meta.yaml
@@ -25,11 +25,13 @@ requirements:
- ruamel.yaml >=0.11.14,<0.19
- conda-standalone
- jinja2
+ - jsonschema >=4
- pillow >=3.1 # [win or osx]
- nsis >=3.08 # [win]
run_constrained: # [unix]
- nsis >=3.08 # [unix]
- conda-libmamba-solver !=24.11.0
+ - pydantic >=2
test:
source_files:
diff --git a/scripts/make_docs.py b/scripts/make_docs.py
index 03e2a801a..51bbaf67a 100644
--- a/scripts/make_docs.py
+++ b/scripts/make_docs.py
@@ -7,15 +7,16 @@
import jinja2
-from constructor import construct
+from constructor._schema import ConstructorConfiguration
from constructor.conda_interface import SUPPORTED_PLATFORMS
+from constructor.construct import ns_platform
REPO_ROOT = dirname(dirname(__file__))
sys.path.insert(0, REPO_ROOT)
-valid_selectors = construct.ns_platform(sys.platform)
+valid_selectors = ns_platform(sys.platform)
template = """