adapt docs

rust/Earthfile

@@ -71,7 +71,7 @@ CARGO:
 #   - EARTHLY_RUST_TARGET_CACHE: Code of the mount cache for the target folder.
 # Notice that in order to run this function, +INIT must be called first.
 # Example:
-#   DO gradle+RUST_GET_MOUNT_CACHE
+#   DO rust+RUST_GET_MOUNT_CACHE
 #   RUN --mount=$EARTHLY_RUST_CARGO_HOME_CACHE --mount=$EARTHLY_RUST_TARGET_CACHE cargo build --release
 GET_RUST_CACHE_MOUNTS:
     COMMAND
@@ -80,13 +80,15 @@ GET_RUST_CACHE_MOUNTS:
     ENV EARTHLY_RUST_CARGO_HOME_CACHE="type=cache,mode=0777,id=$EARTHLY_CACHE_PREFIX#cargo-home,sharing=shared,target=$CARGO_HOME"
     ENV EARTHLY_RUST_TARGET_CACHE="type=cache,mode=0777,id=${EARTHLY_CACHE_PREFIX}#target#${EARTHLY_TARGET_NAME},sharing=locked,target=target"
 
-# COPY_OUTPUT copies files out from the target cache to the image layers.
+# COPY_OUTPUT copies files out of the target cache into the image layers.
 # Use this function when you want to SAVE an ARTIFACT from the target folder (mounted cache), always trying to minimize the total size of the copied fileset.
 # Notice that in order to run this function, +GET_RUST_CACHE_MOUNTS or +CARGO must be called first.
 # Arguments:
 #   - output: Regex matching output artifacts files to be copied to ./target folder in the caller filesystem (image layers).
 # Example:
-#   --output="release/[^\./]+" would keep all the files in /target/release that don't have any extension.
+#   DO rust+RUST_GET_MOUNT_CACHE
+#   RUN --mount=$EARTHLY_RUST_CARGO_HOME_CACHE --mount=$EARTHLY_RUST_TARGET_CACHE cargo build --release
+#   DO rust+COPY_OUTPUT --output="release/[^\./]+" # Keep all the files in /target/release that don't have any extension.
 COPY_OUTPUT:
     COMMAND
     ARG --required output

rust/README.md

@@ -13,8 +13,7 @@ IMPORT github.com/earthly/lib/rust:<version/commit> AS rust
 
 ## +INIT
 
-This function stores the configuration required by the other functions in the build environment filesystem, and installs required dependencies.
-
+This function sets some configuration in the environment (used by following functions), and installs required dependencies.
 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
@@ -25,8 +24,9 @@ DO rust+INIT ...
 ```
 
 ### Arguments
-#### `cache_id`
-Overrides default ID of the global `$CARGO_HOME` cache. Its value is exported to the build environment under the entry: `$EARTHLY_CARGO_HOME_CACHE_ID`.
+#### `cache_prefix`
+Overrides cache prefix for cache IDS. Its value is exported to the build environment under the entry: `$EARTHLY_CACHE_PREFIX`. 
+By default `${EARTHLY_TARGET_PROJECT_NO_TAG}#${OS_RELEASE}#earthly-cargo-cache`
 
 #### `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.
@@ -64,28 +64,40 @@ For example `--output="release/[^\./]+"` would keep all the files in `/target/re
 ### Thread safety
 This function is thread safe. Parallel builds of targets calling this function should be free of race conditions.
 
-## +RUN_WITH_CACHE
+## +GET_RUST_CACHE_MOUNTS
 
-`+RUN_WITH_CACHE` runs the passed command with the CARGO caches mounted.
+Sets the following entries in the environment, to be used to mount the cargo caches.
+ - `EARTHLY_RUST_CARGO_HOME_CACHE`: Code of the mount cache for the cargo home.
+ - `EARTHLY_RUST_TARGET_CACHE`: Code of the mount cache for the target folder.
 
-Notice that in order to run this function, [+INIT](#init) must be called first. This function exports the target cache mount ID under the env entry: `$TARGET_CACHE_ID`.
+Notice that in order to run this function, [+INIT](#init) must be called first.
 
-### Arguments
-#### `command (required)`
-Command to run, can be any expression.
+### Example
+
+```earthfile
+cross:
+  ...
+  DO rust+GET_RUST_CACHE_MOUNTS
+  WITH DOCKER
+    RUN --mount=$EARTHLY_RUST_CARGO_HOME_CACHE --mount=$EARTHLY_RUST_TARGET_CACHE  cross build --target $TARGET --release
+  END
+```
+## COPY_OUTPUT
+This function copies files out of the target cache into the image layers.
+Use it function when you want to `SAVE ARTIFACT` from the target folder (mounted cache), always trying to minimize the total size of the copied fileset.
 
-#### `cargo_home_cache_id`
-ID of the cargo home cache mount. By default: `$CARGO_HOME_CACHE_ID` as exported by `+INIT`
+Notice that in order to run this function, `+GET_RUST_CACHE_MOUNTS` or `+CARGO` must be called first.
 
-#### `target_cache_id`
-ID of the target cache mount. By default: `${CARGO_HOME_CACHE_ID}#${EARTHLY_TARGET_NAME}`
+### Arguments
+#### `output` 
+Regex matching output artifacts files to be copied to `./target` folder in the caller filesystem (image layers).
 
 ### Example
-Show `$CARGO_HOME` cached-entries size:
-
 ```earthfile
-DO rust-udc+RUN_WITH_CACHE --command "du \$CARGO_HOME"
-```
+DO rust+RUST_GET_MOUNT_CACHE
+RUN --mount=$EARTHLY_RUST_CARGO_HOME_CACHE --mount=$EARTHLY_RUST_TARGET_CACHE cargo build --release
+DO rust+COPY_OUTPUT --output="release/[^\./]+" # Keep all the files in /target/release that don't have any extension.
+``
 
 ## Complete example