From e2d00a3a67329131d98c84503a499395579ae1da Mon Sep 17 00:00:00 2001 From: Bianca Henderson Date: Thu, 22 Feb 2024 19:05:20 -0500 Subject: [PATCH 1/3] Initial batch of docs edits --- README.md | 12 +++++------- docs/automatic_linting.md | 4 ++-- docs/available_jinja.md | 35 ++++++++++++++++++----------------- docs/build_options.md | 12 ++++++------ docs/build_script.md | 6 +++--- docs/cli_usage.md | 19 ++++++++----------- docs/index.md | 31 +++++++++++-------------------- docs/recipe_file.md | 6 +++--- 8 files changed, 56 insertions(+), 69 deletions(-) diff --git a/README.md b/README.md index 35234dd02..522b3dad3 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ binaries / packages from a simple recipe format. The recipe format is heavily inspired by `conda-build` and `boa`, and the output of a regular `rattler-build` run is a package that can be installed using `mamba`, `rattler` or `conda`. -`rattler-build` does not have any dependencies on `conda-build` or `Python` and +`rattler-build` does not have any dependencies on `conda-build` or Python and works as a standalone binary. ![](https://user-images.githubusercontent.com/885054/244683824-fd1b3896-84c7-498c-b406-40ab2a9e450c.svg) @@ -70,7 +70,7 @@ self-contained. libraries and executables to make it relative * `patchelf` is required on Linux to rewrite the `rpath` and `runpath` of shared libraries and executables -* `git` to checkout Git repositories (not implemented yet, but will require git +* `git` to checkout Git repositories (not implemented yet, but will require `git` in the future) * `msvc` on Windows because we cannot ship the MSVC compiler on conda-forge (needs to be installed on the host machine) @@ -85,9 +85,7 @@ here](https://prefix-dev.github.io/rattler-build). ### GitHub Action -There is a GitHub Action for rattler-build. -It can be used to install `rattler-build` in CI/CD workflows and run a build command. -Please check out the [GitHub Action documentation](https://github.com/prefix-dev/rattler-build-action) for more information. +There is a GitHub Action for `rattler-build`. It can be used to install `rattler-build` in CI/CD workflows and run a build command. Please check out the [GitHub Action documentation](https://github.com/prefix-dev/rattler-build-action) for more information. ### Usage @@ -278,7 +276,7 @@ about: For this recipe, two additional script files (`build.sh` and `build.bat`) are needed. -**build.sh** +**`build.sh`** ```bash #!/bin/bash @@ -306,7 +304,7 @@ make install rm -rf "${PREFIX}/share" ``` -**build.bat** +**`build.bat`** ```cmd mkdir build diff --git a/docs/automatic_linting.md b/docs/automatic_linting.md index 062e2f1ab..bf708dcbb 100644 --- a/docs/automatic_linting.md +++ b/docs/automatic_linting.md @@ -3,12 +3,12 @@ The new recipe format comes with a strict JSON scheme. You can find the scheme [in this repository](https://github.com/prefix-dev/recipe-format). -It's implemented with `pydantic` and renders to a JSON schema file. The [YAML +It is implemented with `pydantic` and renders to a JSON schema file. The [YAML language server extension in VSCode](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) can recognize the scheme and give helpful hints during editing. -With the YAML language server installed the automatic linting can be enabled by +With the YAML language server installed, the automatic linting can be enabled by adding the following line to the top of the recipe file: ```yaml diff --git a/docs/available_jinja.md b/docs/available_jinja.md index f27e3acd7..a9a5e4846 100644 --- a/docs/available_jinja.md +++ b/docs/available_jinja.md @@ -6,14 +6,14 @@ ### The compiler function -The compiler function can be used to put together a compiler that works for the current platform and the compilation "target_platform". +The compiler function can be used to put together a compiler that works for the current platform and the compilation "`target_platform`". The syntax looks like: `${{ compiler('c') }}` where `'c'` signifies the programming language that is used. This function evaluates to `_ `. -For example, when compiling _on_ linux and to linux-64, this function evaluates to `gcc_linux-64`. +For example, when compiling _on_ `linux` and _to_ `linux-64`, this function evaluates to `gcc_linux-64`. The values can be influenced by the `variant_configuration`. -The `_compiler` and `_compiler_version` variables are the keys with influence, for example: +The `_compiler` and `_compiler_version` variables are the keys with influence. See below for an example: ```yaml c_compiler: @@ -22,21 +22,21 @@ c_compiler_version: - 9.0 ``` -Would select the `clang` compiler in version `9.0`. Note that the final output will still contain the `target_platform`, so that the full compiler will read `clang_linux-64 9.0` when compiling with `--target-platform linux-64`. +The variables shown above would select the `clang` compiler in version `9.0`. Note that the final output will still contain the `target_platform`, so that the full compiler will read `clang_linux-64 9.0` when compiling with `--target-platform linux-64`. -## The `pin_subpackage` function +### The `pin_subpackage` function - `${{ pin_subpackage("mypkg", min_pin="x.x", max_pin="x.x.x") }}` creates a pin to another output in the recipe. -## The `pin_compatible` function +### The `pin_compatible` function - `pin_compatible` pins a package in the run requirements based on the resolved package of the `host` or `build` section. -## The `cdt` function +### The `cdt` function -- `${{ cdt("mypkg") }}` creates a cross dependency to another output in the recipe. +- `${{ cdt("mypkg") }}` creates a cross-dependency to another output in the recipe. -This function helps add Core Dependency Tree packages as dependencies by converting packages as required according to hard-coded logic. +This function helps add Core Dependency Tree packages as dependencies by converting packages as required according to hard-coded logic. See below for an example of how this function can be used: ```yaml # on x86_64 system @@ -45,25 +45,26 @@ cdt('package-name') # outputs: package-name-cos6-x86_64 cdt('package-name') # outputs: package-name-cos6-aarch64 ``` -## The `hash` variable +### The `hash` variable -- `${{ hash }}` this is the variant hash and is useful in the build string computation +- `${{ hash }}` is the variant hash and is useful in the build string computation. -## The `version_to_buildstring` function -- `${{ python | version_to_buildstring }}` converts a version from the variant to a build string (removes `.` and takes only the first two elements of the version). +### The `version_to_buildstring` function +- `${{ python | version_to_buildstring }}` converts a version from the variant to a build string (it removes the `.` character and takes only the first two elements of the version). -## The `env` object +### The `env` object You can use the `env` object to retrieve environment variables and forward them to your build script. There are two ways to do this: - `${{ env.get("MY_ENV_VAR") }}` will return the value of the environment variable `MY_ENV_VAR` or throw an error if it is not set. - `${{ env.get_default("MY_ENV_VAR", "default_value") }}` will return the value of the environment variable `MY_ENV_VAR` or `"default_value"` if it is not set. -You can also check for existence of an environment variable: +You can also check for the existence of an environment variable: - `${{ env.exists("MY_ENV_VAR") }}` will return `true` if the environment variable `MY_ENV_VAR` is set and `false` otherwise. ## Default Jinja filters -- default jinja filters are available: `lower`, `upper`, indexing into characters: `https://myurl.com/{{ name[0] }}/{{ name | lower }}_${{ version }}.tar.gz`. - A list of all the builtin filters can be found under: [Link](https://docs.rs/minijinja/latest/minijinja/filters/index.html#functions) +The following Jinja filters are available: `lower`, `upper`, indexing into characters (e.g. `https://myurl.com/{{ name[0] }}/{{ name | lower }}_${{ version }}.tar.gz`). + +Navigate to the [Minijinja documentation](https://docs.rs/minijinja/latest/minijinja/filters/index.html#built-in-filters) for a list of all available built-in filters. diff --git a/docs/build_options.md b/docs/build_options.md index a81755c5f..8607d1c74 100644 --- a/docs/build_options.md +++ b/docs/build_options.md @@ -17,7 +17,7 @@ already in the environment as part of some other host dependency. This is normal "clobbering" and should be used with caution (since packages should not have any overlapping files). The `always_copy_files` option can be used to copy files instead of linking them. -This is useful for files that might be modified inside the environment (for example configuration files). +This is useful for files that might be modified inside the environment (e.g. configuration files). Normally, files are linked from a central cache into the environment to save space – that means that files modified in one environment will be modified in all environments. This is not always desirable, and in that case you can use the `always_copy_files` option. @@ -140,7 +140,7 @@ build: ## Dynamic linking configuration -After the package is build, rattler-build performs some "post-processing" on the +After the package is built, rattler-build performs some "post-processing" on the binaries and libraries. This entails making the shared libraries relocatable and checking that all @@ -148,7 +148,7 @@ linked libraries are present in the run requirements. The following settings control this behavior. With the `rpath` option you can forcibly set the `rpath` of the shared -libraries. The path is relative to the install prefix. Any rpath setting is +libraries. The path is relative to the install prefix. Any `rpath` setting is ignored on Windows. The `rpath_allowlist` option can be used to allow the `rpath` to point to @@ -160,7 +160,7 @@ If you want to stop `rattler-build` from relocating the binaries, you can set `binary_relocation` to `false`. If you want to only relocate some binaries, you can select the relevant ones with a glob pattern. -To read more about rpaths and how rattler-build creates relocatable binary packages, +To read more about `rpath`s and how rattler-build creates relocatable binary packages, see the [internals](internals.md) docs. If you link against some libraries (possibly even outside of the prefix, in a @@ -169,11 +169,11 @@ against these and suppress any warnings. This list is pre-populated with a list of known system libraries on the different operating systems. As part of the post-processing, `rattler-build` checks for overlinking and -overdepending. Overlinking is when a binary links against a library that is not +overdepending. "Overlinking" is when a binary links against a library that is not specified in the run requirements. This is usually a mistake because the library would not be present in the environment when the package is installed. -Conversely, overdepending is when a library is part of the run requirements, but +Conversely, "overdepending" is when a library is part of the run requirements, but is not actually used by any of the binaries/libraries in the package. ```yaml title="recipe.yaml" diff --git a/docs/build_script.md b/docs/build_script.md index f74b1f6ee..9c3816a5d 100644 --- a/docs/build_script.md +++ b/docs/build_script.md @@ -47,7 +47,7 @@ noted, no variables are inherited from the shell environment in which you invoke : Represents the number of CPUs on the system. `SHLIB_EXT` -: Denotes the shared library extension specific to the operating system (e.g., .so for Linux, .dylib for macOS, and .dll for Windows). +: Denotes the shared library extension specific to the operating system (e.g. `.so` for Linux, `.dylib` for macOS, and `.dll` for Windows). `HTTP_PROXY` : Inherited from the user's shell environment, specifying the HTTP proxy settings. @@ -80,10 +80,10 @@ noted, no variables are inherited from the shell environment in which you invoke : The version of the package currently under construction. `PKG_BUILD_STRING` -: The complete build string of the package being built, including the hash (e.g., py311h21422ab_0). +: The complete build string of the package being built, including the hash (e.g. py311h21422ab_0). `PKG_HASH` -: Represents the hash of the package being built, excluding the leading 'h' (e.g., 21422ab). This is applicable from Conda-build 3.0 onwards. +: Represents the hash of the package being built, excluding the leading 'h' (e.g. 21422ab). This is applicable from conda-build 3.0 onwards. `PYTHON` : The path to the Python executable in the host prefix. Python is installed in the host prefix only when it is listed as a host requirement. diff --git a/docs/cli_usage.md b/docs/cli_usage.md index bc3e4ff86..777bc910e 100644 --- a/docs/cli_usage.md +++ b/docs/cli_usage.md @@ -2,10 +2,9 @@ ## Shell Completions -We support shell completions through clap-complete. -You can generate them for your shell using the `completion` command. +We support shell completions through [`clap_complete`](https://crates.io/crates/clap_complete). You can generate them for your shell using the `completion` command. -You can add the completions to your shell by adding the following to your shell's configuration file. +You can add the completions to your shell by adding the following to your shell's configuration file: ```sh # For bash (add this to ~/.bashrc) @@ -16,8 +15,7 @@ eval "$(rattler-build completion --shell=zsh)" rattler-build completion --shell=fish | source ``` -Ensure that whereever you install the is pointed to by your FPATH (for zsh or equivalent in other shells). -Now you can use TAB or your configured completion key. :3 +Ensure that wherever you install `rattler-build` is pointed to by your `FPATH` (for `zsh` or equivalent in other shells), after which point you can use TAB or any configured completion key of choice. 😄 ```sh $ rattler-build @@ -42,17 +40,16 @@ rattler-build build --package-format conda:max --compression-threads 10 -r recip ## Logs -Rattler-build knows 3 different log-styles: `fancy`, `plain` and `json`. -You can configure them with the `--log-style=