diff --git a/guide/src/SUMMARY.md b/guide/src/SUMMARY.md index b28df117f..32ac13513 100644 --- 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 index 517668066..c040c3c00 100644 --- 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: + ... + Rustc flags OPTIONS: -b, --bindings Which kind of bindings to use. Possible values are pyo3, rust-cpython, cffi and bin - --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 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 - The path to the Cargo.toml + -j, --jobs + Number of parallel jobs, defaults to # of CPUs - [default: Cargo.toml] + --profile + Build artifacts with the specified Cargo profile - --release - Pass --release to cargo + -F, --features + Space or comma separated list of features to activate - --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 + Build for the target triple + + [env: CARGO_BUILD_TARGET=] + + --target-dir + Directory for all generated artifacts + + -m, --manifest-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 + 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 + Override a configuration value (unstable) + + -Z + Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details + + --timings[=...] + 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 index e1466e584..da59195e8 100644 --- 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 - Which kind of bindings to use. Possible values are pyo3, rust-cpython, cffi and bin +ARGS: + ... + Rustc flags - --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 ... 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 + -i, --interpreter ... The python versions to build wheels for, given as the names of the interpreters. Uses autodiscovery if not explicitly set - -m, --manifest-path - The path to the Cargo.toml + -f, --find-interpreter + Find interpreters from the host machine - --sdist - Build a source distribution + -b, --bindings + Which kind of bindings to use. Possible values are pyo3, rust-cpython, cffi and bin -o, --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 - 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 - 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 + Number of parallel jobs, defaults to # of CPUs - Make sure you installed zig with `pip install maturin[zig]` + --profile + Build artifacts with the specified Cargo profile + + -F, --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 + Build for the target triple + + [env: CARGO_BUILD_TARGET=] + + --target-dir + Directory for all generated artifacts + + -m, --manifest-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 + 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 + Override a configuration value (unstable) + + -Z + Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details + + --timings[=...] + 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 index a370db8e3..0b10ac556 100644 --- 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 new file mode 100644 index 000000000..b4456e375 --- /dev/null +++ b/guide/src/migration.md @@ -0,0 +1,28 @@ +# 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. + +### `--repository-url` only accepts full URL now + +Previously `--repository-url` option in `maturin upload` and `maturin publish` commands accepts both +repository name and URL. maturin 0.13 changed `--repository-url` to only accept full URL and added a +new `--repository` for the repository name. This new behavior matches `twine upload`.