diff --git a/README.md b/README.md index f12208f..8f3f962 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # lib -Earthly's official collection of [UDCs](https://docs.earthly.dev/docs/guides/udc). +Earthly's official collection of [functions](https://docs.earthly.dev/docs/guides/functions). ## Contributing diff --git a/rust/Earthfile b/rust/Earthfile index e386458..68aa495 100644 --- a/rust/Earthfile +++ b/rust/Earthfile @@ -1,6 +1,6 @@ VERSION --global-cache 0.7 -# INIT stores the configuration required for the other UDCs in the filesystem, and installs required dependencies. +# INIT installs some required dependencies and stores in the filesystem the configuration that will be available for the rest of functions. # - cache_id: Overrides default ID of the global $CARGO_HOME cache. Its value is exported to the build environment under the entry: $CARGO_HOME_CACHE_ID # - keep_fingerprints (false): Instructs the following +CARGO calls to don't remove the Cargo fingerprints of the source packages. Use only when source packages have been COPYed with --keep-ts option. # - sweep_days (4): +CARGO uses cargo-sweep to clean build artifacts that haven't been accessed for this number of days. @@ -35,8 +35,8 @@ INIT: RUN echo "$sweep_days">/tmp/earthly/cfg/sweep_days # CARGO runs the cargo command "cargo $args". -# This UDC is thread safe. Parallel builds of targets calling this UDC should be free of race conditions. -# Notice that in order to run this UDC, +INIT must be called first. +# This function is thread safe. Parallel builds of targets calling this function should be free of race conditions. +# Notice that in order to run this function, +INIT must be called first. # Arguments: # - args: Cargo subcommand and its arguments. Required. # - output: Regex to match the files within the target folder to be copied from the cache to the caller filesystem (image layers). @@ -73,7 +73,7 @@ CARGO: END # RUN_WITH_CACHE runs the passed command with the CARGO caches mounted. -# Notice that in order to run this UDC, +INIT must be called first. +# Notice that in order to run this function, +INIT must be called first. # Arguments: # - command (required): Command to run, can be any expression. # @@ -86,7 +86,7 @@ RUN_WITH_CACHE: # Save to restore at the end. ARG ORIGINAL_CARGO_HOME=$CARGO_HOME ARG ORIGINAL_CARGO_INSTALL_ROOT=$CARGO_INSTALL_ROOT - # Make sure that crates installed though this UDC are stored in the original cargo home, and not in the cargo home within the mount cache. + # Make sure that crates installed though this function are stored in the original cargo home, and not in the cargo home within the mount cache. # This way, if BK garbage-collects them, the build is not broken. ENV CARGO_INSTALL_ROOT=$ORIGINAL_CARGO_HOME # We change $CARGO_HOME while keeping $ORIGINAL_CARGO_HOME/bin directory in the path. This way, the Cargo binary is still accessible and the whole $CARGO_HOME is within the global cache diff --git a/rust/README.md b/rust/README.md index 346bd21..6efe99e 100644 --- a/rust/README.md +++ b/rust/README.md @@ -1,8 +1,8 @@ # lib/rust -Earthly's official collection of rust [UDCs](https://docs.earthly.dev/docs/guides/udc). +Earthly's official collection of Rust [functions](https://docs.earthly.dev/docs/guides/functions). -First, import the UDC up in your Earthfile: +First, import the library up in your Earthfile: ```earthfile VERSION --global-cache 0.7 IMPORT github.com/earthly/lib/rust: AS rust @@ -11,9 +11,9 @@ IMPORT github.com/earthly/lib/rust: AS rust ## +INIT -This UDC stores the configuration required by the other UDCs in the build environment filesystem, and installs required dependencies. +This function stores the configuration required by the other functions in the build environment filesystem, and installs required dependencies. -It must be called once per build environment, to avoid passing repetitive arguments to the UDCs called after it, and to install required dependencies before the source files are copied from the build context. +It must be called once per build environment, to avoid passing repetitive arguments to the functions called after it, and to install required dependencies before the source files are copied from the build context. ### Usage @@ -29,16 +29,16 @@ Overrides default ID of the global `$CARGO_HOME` cache. Its value is exported to #### `keep_fingerprints (false)` Instructs the following `+CARGO` calls to don't remove the Cargo fingerprints of the source packages. Use only when source packages have been COPYed with `--keep-ts `option. Cargo caches compilations of packages in `target` folder based on their last modification timestamps. -By default, this UDC removes the fingerprints of the packages found in the source code, to force their recompilation and work even when the Earthly `COPY` commands used overwrote the timestamps. +By default, this function removes the fingerprints of the packages found in the source code, to force their recompilation and work even when the Earthly `COPY` commands used overwrote the timestamps. #### `sweep_days (4)` `+CARGO` calls use cargo-sweep to clean build artifacts that haven't been accessed for this number of days. ## +CARGO -This UDC runs the cargo command `cargo $args` caching the contents of `$CARGO_HOME` and `target` for future builds of the same calling target. +This function runs the cargo command `cargo $args` caching the contents of `$CARGO_HOME` and `target` for future builds of the same calling target. -Notice that in order to run this UDC, [+INIT](#init) must be called first. +Notice that in order to run this function, [+INIT](#init) must be called first. ### Usage @@ -60,13 +60,13 @@ Use this argument when you want to `SAVE ARTIFACT` from the target folder (mount For example `--output="release/[^\./]+"` would keep all the files in `/target/release` that don't have any extension. ### Thread safety -This UDC is thread safe. Parallel builds of targets calling this UDC should be free of race conditions. +This function is thread safe. Parallel builds of targets calling this function should be free of race conditions. ## +RUN_WITH_CACHE `+RUN_WITH_CACHE` runs the passed command with the CARGO caches mounted. -Notice that in order to run this UDC, [+INIT](#init) must be called first. +Notice that in order to run this function, [+INIT](#init) must be called first. ### Arguments #### `command (required)` @@ -103,7 +103,7 @@ The Earthfile would look like: ```earthfile VERSION --global-cache 0.7 -# Importing UDC definition from default branch (in a real case, specify version or commit to guarantee immutability) +# Imports the library definition from default branch (in a real case, specify version or commit to guarantee immutability) IMPORT github.com/earthly/lib/rust AS rust install: @@ -114,7 +114,7 @@ install: RUN rustup component add clippy RUN rustup component add rustfmt # Call +INIT before copying the source file to avoid installing depencies every time source code changes. - # This parametrization will be used in future calls to UDCs of the library + # This parametrization will be used in future calls to functions of the library DO rust+INIT --keep_fingerprints=true source: diff --git a/utils/dind/tests/Earthfile b/utils/dind/tests/Earthfile index d997e88..a207ce7 100644 --- a/utils/dind/tests/Earthfile +++ b/utils/dind/tests/Earthfile @@ -17,7 +17,7 @@ test-install-dind-for-image: ARG --required base_image FROM alpine ARG TARGETPLATFORM - IF [ "${base_image%:*}" = "amazonlinux" ] && [ "$TARGETPLATFORM" = "linux/arm64" ] # no amazonlinux:1 for arm64/UDC not supported atm for amazonlinux:2 on arm - skipping + IF [ "${base_image%:*}" = "amazonlinux" ] && [ "$TARGETPLATFORM" = "linux/arm64" ] # no amazonlinux:1 for arm64/function not supported atm for amazonlinux:2 on arm - skipping RUN echo skipping $base_image with platform $TARGETPLATFORM ELSE FROM "$base_image"