diff --git a/README.Rmd b/README.Rmd index 07231c9..bb444ba 100644 --- a/README.Rmd +++ b/README.Rmd @@ -52,9 +52,9 @@ pre-compiled binaries for Windows and macOS — no Rust toolchain needed. The r-universe binaries compile the zarrs backend with local filesystem I/O, synchronous HTTP reads, gzip/zstd/blosc codecs, sharding, and S3/GCS cloud -store support via `object_store`. The build system enables these features -automatically when `NOT_CRAN` is set (which r-universe does). To compile with -a different feature set, set `PIZZARR_FEATURES` explicitly (see below). +store support via `object_store`. Any build that compiles Rust enables these +features by default. To compile with a different feature set, set +`PIZZARR_FEATURES` explicitly (see below). `pizzarr_compiled_features()` lists what the zarrs backend provides, and `pizzarr_upgrade()` prints the install command when zarrs is not compiled in. @@ -80,10 +80,10 @@ The build system uses two environment variables to control compilation: skips link-time optimization and does not strip symbols. Use this during active development on the Rust code. - **`PIZZARR_FEATURES`** — a comma-separated list of extra Cargo features. - When `NOT_CRAN` is set and `PIZZARR_FEATURES` is empty, the build defaults - to `s3,gcs` (S3 and GCS cloud store support via `object_store` and `tokio`). - Set this explicitly to override — e.g., `PIZZARR_FEATURES=none` for default - features only, or `PIZZARR_FEATURES=s3` for S3 without GCS. + When unset, the build defaults to `s3,gcs` (S3 and GCS cloud store support + via `object_store` and `tokio`, which also pulls in blosc and sharding). + Set this explicitly to override — e.g., `PIZZARR_FEATURES=none` for Cargo's + default features only, or `PIZZARR_FEATURES=s3` for S3 without GCS. A release build (no `DEBUG`) uses LTO, single codegen unit, and symbol stripping — fast at runtime but takes several minutes to compile from scratch. @@ -93,15 +93,15 @@ stripping — fast at runtime but takes several minutes to compile from scratch. DEBUG=1 R CMD INSTALL . # Production: slow first build, fast runtime, S3/GCS included -NOT_CRAN=true R CMD INSTALL . - -# Production with default features only (no cloud stores) R CMD INSTALL . + +# Production with Cargo default features only (no cloud stores) +PIZZARR_FEATURES=none R CMD INSTALL . ``` -`NOT_CRAN` is set automatically when `DEBUG` is present. For builds without -vendored crates (the normal case for local development), `NOT_CRAN` prevents -the build system from attempting offline compilation. +`NOT_CRAN=true` opts builds out of the offline-vendored-crates path used for +CRAN; it's set automatically when `DEBUG` is present and only matters when +`src/rust/vendor.tar.xz` is also present. Development happens on the `develop` branch. See [CONTRIBUTING.md](https://github.com/zarr-developers/pizzarr/blob/main/CONTRIBUTING.md) diff --git a/README.md b/README.md index ad25f6d..66439e4 100644 --- a/README.md +++ b/README.md @@ -41,10 +41,9 @@ toolchain needed. The r-universe binaries compile the zarrs backend with local filesystem I/O, synchronous HTTP reads, gzip/zstd/blosc codecs, -sharding, and S3/GCS cloud store support via `object_store`. The -build system enables these features automatically when `NOT_CRAN` is -set (which r-universe does). To compile with a different feature set, -set `PIZZARR_FEATURES` explicitly (see below). +sharding, and S3/GCS cloud store support via `object_store`. Any build +that compiles Rust enables these features by default. To compile with +a different feature set, set `PIZZARR_FEATURES` explicitly (see below). `pizzarr_compiled_features()` lists what the zarrs backend provides, and `pizzarr_upgrade()` prints the install command when zarrs is not @@ -71,10 +70,10 @@ The build system uses two environment variables to control compilation: runtime because it skips link-time optimization and does not strip symbols. Use this during active development on the Rust code. - **`PIZZARR_FEATURES`** — a comma-separated list of extra Cargo - features. When `NOT_CRAN` is set and `PIZZARR_FEATURES` is empty, - the build defaults to `s3,gcs` (S3 and GCS cloud store support via - `object_store` and `tokio`). Set this explicitly to override — e.g., - `PIZZARR_FEATURES=none` for default features only, or + features. When unset, the build defaults to `s3,gcs` (S3 and GCS + cloud store support via `object_store` and `tokio`, which also pulls + in blosc and sharding). Set this explicitly to override — e.g., + `PIZZARR_FEATURES=none` for Cargo's default features only, or `PIZZARR_FEATURES=s3` for S3 without GCS. A release build (no `DEBUG`) uses LTO, single codegen unit, and symbol @@ -86,16 +85,15 @@ scratch. DEBUG=1 R CMD INSTALL . # Production: slow first build, fast runtime, S3/GCS included -NOT_CRAN=true R CMD INSTALL . - -# Production with default features only (no cloud stores) R CMD INSTALL . + +# Production with Cargo default features only (no cloud stores) +PIZZARR_FEATURES=none R CMD INSTALL . ``` -`NOT_CRAN` is set automatically when `DEBUG` is present. For builds -without vendored crates (the normal case for local development), -`NOT_CRAN` prevents the build system from attempting offline -compilation. +`NOT_CRAN=true` opts builds out of the offline-vendored-crates path +used for CRAN; it's set automatically when `DEBUG` is present and only +matters when `src/rust/vendor.tar.xz` is also present. Development happens on the `develop` branch. See [CONTRIBUTING.md](https://github.com/zarr-developers/pizzarr/blob/main/CONTRIBUTING.md) diff --git a/tools/config.R b/tools/config.R index a3f3e1b..0209052 100644 --- a/tools/config.R +++ b/tools/config.R @@ -71,16 +71,17 @@ if (!is_not_cran) { # when DEBUG env var is present we use `--debug` build .profile <- ifelse(is_debug, "", "--release") -# PIZZARR_FEATURES env var enables extra Cargo features (e.g., "s3,gcs"). -# When NOT_CRAN is set (r-universe, DEBUG) and PIZZARR_FEATURES is empty, -# default to "s3,gcs" so r-universe binaries ship with cloud store support. -if (!nzchar(env_features) && is_not_cran) { +# PIZZARR_FEATURES env var enables extra Cargo features. When unset, default +# to "s3,gcs" so every Rust build ships with cloud store + blosc + sharding +# support. The CRAN tier is the pure-R tarball produced by tools/cran-build.sh +# (src/ stripped), so this default never reaches CRAN — it only affects builds +# that actually compile Rust (r-universe binaries, local source installs). +if (!nzchar(env_features)) { env_features <- "s3,gcs" - message("Defaulting PIZZARR_FEATURES to '", env_features, "' (NOT_CRAN build).") + message("Defaulting PIZZARR_FEATURES to '", env_features, "'.") } -# "none" is an escape hatch: suppresses the NOT_CRAN default without -# passing any extra features to Cargo. +# "none" is an escape hatch: build with Cargo's default features only. if (identical(env_features, "none")) { env_features <- "" message("PIZZARR_FEATURES='none': using default Cargo features only.")