Update user guide for the upcoming 0.13 release

PyO3 · Jun 19, 2022 · b504d8e · b504d8e
1 parent 85911ea
commit b504d8e
Show file tree

Hide file tree

Showing 5 changed files with 194 additions and 61 deletions.
diff --git a/guide/src/SUMMARY.md b/guide/src/SUMMARY.md
@@ -12,6 +12,13 @@
 - [Local Development](./develop.md)
 - [Distribution](./distribution.md)
 - [Sphinx Integration](./sphinx.md)
-- [Contributing](./contributing.md)
-    - [Platform Support](./platform_support.md)
+
+---
+
+- [Migration Guide](./migration.md)
 - [Changelog](./changelog.md)
+
+---
+
+- [Contributing](./contributing.md)
+  - [Platform Support](./platform_support.md)
diff --git a/guide/src/develop.md b/guide/src/develop.md
@@ -7,40 +7,88 @@ build a package in debug mode by default and install it to virtualenv.
 
 ```
 USAGE:
-    maturin develop [OPTIONS]
+    maturin develop [OPTIONS] [--] [ARGS]...
+
+ARGS:
+    <ARGS>...
+            Rustc flags
 
 OPTIONS:
     -b, --bindings <BINDINGS>
             Which kind of bindings to use. Possible values are pyo3, rust-cpython, cffi and bin
 
-        --cargo-extra-args <CARGO_EXTRA_ARGS>
-            Extra arguments that will be passed to cargo as `cargo rustc [...] [arg1] [arg2] --`
+    -r, --release
+            Pass --release to cargo
 
-            Use as `--cargo-extra-args="--my-arg"`
+        --strip
+            Strip the library for minimum file size
 
     -E, --extras <EXTRAS>
             Install extra requires aka. optional dependencies
 
             Use as `--extras=extra1,extra2`
 
-    -h, --help
-            Print help information
+    -q, --quiet
+            Do not print cargo log messages
 
-    -m, --manifest-path <MANIFEST_PATH>
-            The path to the Cargo.toml
+    -j, --jobs <N>
+            Number of parallel jobs, defaults to # of CPUs
 
-            [default: Cargo.toml]
+        --profile <PROFILE-NAME>
+            Build artifacts with the specified Cargo profile
 
-        --release
-            Pass --release to cargo
+        --features <FEATURES>...
+            Space or comma separated list of features to activate
 
-        --rustc-extra-args <RUSTC_EXTRA_ARGS>
-            Extra arguments that will be passed to rustc as `cargo rustc [...] -- [arg1] [arg2]`
+        --all-features
+            Activate all available features
 
-            Use as `--rustc-extra-args="--my-arg"`
+        --no-default-features
+            Do not activate the `default` feature
 
-        --strip
-            Strip the library for minimum file size
+        --target <TRIPLE>
+            Build for the target triple
+
+            [env: CARGO_BUILD_TARGET=]
+
+        --target-dir <DIRECTORY>
+            Directory for all generated artifacts
+
+    -m, --manifest-path <PATH>
+            Path to Cargo.toml
+
+        --ignore-rust-version
+            Ignore `rust-version` specification in packages
+
+    -v, --verbose
+            Use verbose output (-vv very verbose/build.rs output)
+
+        --color <WHEN>
+            Coloring: auto, always, never
+
+        --frozen
+            Require Cargo.lock and cache are up to date
+
+        --locked
+            Require Cargo.lock is up to date
+
+        --offline
+            Run without accessing the network
+
+        --config <KEY=VALUE>...
+            Override a configuration value (unstable)
+
+    -Z <FLAG>...
+            Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details
+
+        --timings[=<FMTS>...]
+            Timing output formats (unstable) (comma separated): html, json
+
+        --future-incompat-report
+            Outputs a future incompatibility report at the end of the build (unstable)
+
+    -h, --help
+            Print help information
 ```
 
 ## PEP 660 Editable Installs

diff --git a/guide/src/distribution.md b/guide/src/distribution.md
@@ -71,23 +71,23 @@ or [nanoporetech/fast-ctc-decode](https://github.com/nanoporetech/fast-ctc-decod
 
 ```
 USAGE:
-    maturin build [OPTIONS]
+    maturin build [OPTIONS] [--] [ARGS]...
 
-OPTIONS:
-    -b, --bindings <BINDINGS>
-            Which kind of bindings to use. Possible values are pyo3, rust-cpython, cffi and bin
+ARGS:
+    <ARGS>...
+            Rustc flags
 
-        --cargo-extra-args <CARGO_EXTRA_ARGS>
-            Extra arguments that will be passed to cargo as `cargo rustc [...] [arg1] [arg2] --
-            [...]`
+OPTIONS:
+    -r, --release
+            Build artifacts in release mode, with optimizations
 
-            Use as `--cargo-extra-args="--my-arg"`
+        --strip
+            Strip the library for minimum file size
 
-            Note that maturin invokes cargo twice: Once as `cargo metadata` and then as `cargo
-            rustc`. maturin tries to pass only the shared subset of options to cargo metadata, but
-            this is may be a bit flaky.
+        --sdist
+            Build a source distribution
 
-        --compatibility <compatibility>
+        --compatibility <compatibility>...
             Control the platform tag on linux.
 
             Options are `manylinux` tags (for example `manylinux2014`/`manylinux_2_24`) or
@@ -102,53 +102,95 @@ OPTIONS:
 
             This option is ignored on all non-linux platforms
 
-    -h, --help
-            Print help information
-
-    -i, --interpreter <INTERPRETER>
+    -i, --interpreter <INTERPRETER>...
             The python versions to build wheels for, given as the names of the interpreters. Uses
             autodiscovery if not explicitly set
 
-    -m, --manifest-path <PATH>
-            The path to the Cargo.toml
+    -f, --find-interpreter
+            Find interpreters from the host machine
 
-        --sdist
-            Build a source distribution
+    -b, --bindings <BINDINGS>
+            Which kind of bindings to use. Possible values are pyo3, rust-cpython, cffi and bin
 
     -o, --out <OUT>
             The directory to store the built wheels in. Defaults to a new "wheels" directory in the
             project's target directory
 
-        --release
-            Pass --release to cargo
-
-        --rustc-extra-args <RUSTC_EXTRA_ARGS>
-            Extra arguments that will be passed to rustc as `cargo rustc [...] -- [...] [arg1]
-            [arg2]`
-
-            Use as `--rustc-extra-args="--my-arg"`
-
         --skip-auditwheel
             Don't check for manylinux compliance
 
-        --strip
-            Strip the library for minimum file size
+        --zig
+            For manylinux targets, use zig to ensure compliance for the chosen manylinux version
 
-        --target <TRIPLE>
-            The --target option for cargo
+            Default to manylinux2010/manylinux_2_12 if you do not specify an `--compatibility`
 
-            [env: CARGO_BUILD_TARGET=]
+            Make sure you installed zig with `pip install maturin[zig]`
 
         --universal2
             Control whether to build universal2 wheel for macOS or not. Only applies to macOS
             targets, do nothing otherwise
 
-        --zig
-            For manylinux targets, use zig to ensure compliance for the chosen manylinux version
+    -q, --quiet
+            Do not print cargo log messages
 
-            Default to manylinux2010/manylinux_2_12 if you do not specify an `--compatibility`
+    -j, --jobs <N>
+            Number of parallel jobs, defaults to # of CPUs
 
-            Make sure you installed zig with `pip install maturin[zig]`
+        --profile <PROFILE-NAME>
+            Build artifacts with the specified Cargo profile
+
+        --features <FEATURES>...
+            Space or comma separated list of features to activate
+
+        --all-features
+            Activate all available features
+
+        --no-default-features
+            Do not activate the `default` feature
+
+        --target <TRIPLE>
+            Build for the target triple
+
+            [env: CARGO_BUILD_TARGET=]
+
+        --target-dir <DIRECTORY>
+            Directory for all generated artifacts
+
+    -m, --manifest-path <PATH>
+            Path to Cargo.toml
+
+        --ignore-rust-version
+            Ignore `rust-version` specification in packages
+
+    -v, --verbose
+            Use verbose output (-vv very verbose/build.rs output)
+
+        --color <WHEN>
+            Coloring: auto, always, never
+
+        --frozen
+            Require Cargo.lock and cache are up to date
+
+        --locked
+            Require Cargo.lock is up to date
+
+        --offline
+            Run without accessing the network
+
+        --config <KEY=VALUE>...
+            Override a configuration value (unstable)
+
+    -Z <FLAG>...
+            Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details
+
+        --timings[=<FMTS>...]
+            Timing output formats (unstable) (comma separated): html, json
+
+        --future-incompat-report
+            Outputs a future incompatibility report at the end of the build (unstable)
+
+    -h, --help
+            Print help information
 ```
 
 ### Cross Compiling

diff --git a/guide/src/metadata.md b/guide/src/metadata.md
@@ -107,8 +107,6 @@ in the `tool.maturin` section of `pyproject.toml`.
 
 ```toml
 [tool.maturin]
-# Cargo manifest path
-manifest-path = "Cargo.toml"
 # Include arbitrary files in the sdist
 sdist-include = []
 # Bindings type
@@ -119,8 +117,24 @@ compatibility = "manylinux2014"
 skip-auditwheel = false
 # Strip the library for minimum file size
 strip = true
-# Extra arguments that will be passed to cargo as `cargo rustc [...] [arg1] [arg2] -- [...]`
-cargo-extra-args = ""
+# Build artifacts with the specified Cargo profile
+profile = "release"
+# List of features to activate
+features = ["foo", "bar"]
+# Activate all available features
+all-features = false
+# Do not activate the `default` feature
+no-default-features = false
+# Cargo manifest path
+manifest-path = "Cargo.toml"
+# Require Cargo.lock and cache are up to date
+frozen = false
+# Require Cargo.lock is up to date
+locked = false
+# Override a configuration value (unstable)
+config = []
+# Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details
+unstable-flags = []
 # Extra arguments that will be passed to rustc as `cargo rustc [...] -- [...] [arg1] [arg2]`
-rustc-extra-args = ""
+rustc-args = []
 ```
diff --git a/guide/src/migration.md b/guide/src/migration.md
@@ -0,0 +1,22 @@
+# Migrating from older maturin versions
+
+This guide can help you upgrade code through breaking changes from one maturin version to the next.
+For a detailed list of all changes, see the [CHANGELOG](changelog.md).
+
+## From 0.12.* to 0.13
+
+### Drop support for Python 3.6
+
+maturin 0.13 has dropped support for Python 3.6, to support Python 3.6 you can use the old 0.12 versions.
+
+### Source distributions are not built by default
+
+maturin 0.13 replaced `--no-sdist` with the new `--sdist` option, source distributions are now only built
+when `--sdist` is specified.
+
+### Only build wheels for current Python interpreter in `PATH` by default
+
+maturin 0.13 no longer searches for Python interpreters by default and only build wheels for the current
+Python interpreter (i.e. `python3`) in `PATH`.
+
+To enable the old behavior, use the new `--find-interpreter` option.