diff --git a/pyoxidizer/docs/pyoxidizer_rust_projects.rst b/pyoxidizer/docs/pyoxidizer_rust_projects.rst index ac2ebaf63..1ad920596 100644 --- a/pyoxidizer/docs/pyoxidizer_rust_projects.rst +++ b/pyoxidizer/docs/pyoxidizer_rust_projects.rst @@ -164,10 +164,7 @@ interpreter use the ``snmalloc`` allocator. Using Cargo With Generated Rust Projects ======================================== -Rust developers will probably want to use ``cargo`` instead of ``pyoxidizer`` -for building auto-generated Rust projects. This is supported, but behavior can -be very finicky. - +Building from a Rust project is not turn-key like PyOxidizer is. PyOxidizer has to do some non-conventional things to get Rust projects to build in very specific ways. Commands like ``pyoxidizer build`` abstract away all of this complexity for you. @@ -216,3 +213,41 @@ file contains some commented out settings that may need to be set for some configurations (e.g. the ``standalone_static`` Windows distributions). Please consult this file if running into build errors when not building through ``pyoxidizer``. + +An Example and Further Reference +================================== + +Starting from a project freshly created with ``pyoxidizer init-rust-project sample``, +you'll first need to generate the build artifacts:: + + $ PYOXIDIZER_EXECUTABLE=$HOME/.cargo/bin/pyoxidizer \ + PYO3_PYTHON=$HOME/python/install/bin/python3.9 \ + PYOXIDIZER_CONFIG=$(pwd)/pyoxidizer.bzl \ + TARGET=x86_64-apple-darwin \ + CARGO_MANIFEST_DIR=. \ + OUT_DIR=target/out \ + PROFILE=debug \ + pyoxidizer run-build-script build.rs + +That will put the artifacts in target/out. + +Then you can run cargo to build your crate:: + + $ PYOXIDIZER_REUSE_ARTIFACTS=1 \ + PYOXIDIZER_ARTIFACT_DIR=$(pwd)/target/out \ + PYOXIDIZER_EXECUTABLE=$HOME/.cargo/bin/pyoxidizer \ + PYOXIDIZER_CONFIG=$(pwd)/pyoxidizer.bzl \ + PYO3_CONFIG_FILE=$(pwd)/target/out/pyo3-build-config-file.txt cargo \ + build --no-default-features --features \ + "build-mode-prebuilt-artifacts global-allocator-jemalloc allocator-jemalloc" + +After building, you should find an executable in target/debug/. + +Note that currently this does not produce any files that have been redirected to the filesystem, +such as extension modules. For now you'll need to copy them in from a normal pyoxidizer run, or +see https://github.com/indygreg/PyOxidizer/pull/466 + +On Windows, the paths will need updating, and the jemalloc features will need to be removed. + +If you wish to dig further into how PyOxidizer builds projects, project_building.rs +is a good place to start. \ No newline at end of file diff --git a/pyoxidizer/src/projectmgmt.rs b/pyoxidizer/src/projectmgmt.rs index c3cc45137..5112641a2 100644 --- a/pyoxidizer/src/projectmgmt.rs +++ b/pyoxidizer/src/projectmgmt.rs @@ -356,26 +356,26 @@ pub fn init_rust_project( "A new Rust binary application has been created in {}", project_path.display() ); - println!(); - println!("This application can be built by doing the following:"); - println!(); - println!(" $ cd {}", project_path.display()); - println!(" $ pyoxidizer build"); - println!(" $ pyoxidizer run"); - println!(); - println!("The default configuration is to invoke a Python REPL. You can"); - println!("edit the various pyoxidizer.*.bzl config files or the main.rs "); - println!("file to change behavior. The application will need to be rebuilt "); - println!("for configuration changes to take effect."); - println!(); - println!("IMPORTANT: use of `cargo` for direct project building and running"); - println!("is possible, but likely requires setting environment variables"); - println!("like PYOXIDIZER_EXE (the path to the `pyoxidizer` that the build.rs"); - println!("build script should use) and PYO3_PYTHON (the path to the"); - println!("Python interpreter executable used to configure the Rust crates that"); - println!("link against libpython). Search the documentation for references to"); - println!("these variables for troubleshooting tips. For best results, use"); - println!("the aforementioned `pyoxidizer` commands to build Rust projects."); + print!( + r#" +This application can be built most easily by doing the following: + + $ cd {project_path} + $ pyoxidizer run + +Note however that this will bypass all the Rust code in the project +folder, and build the project as if you had only created a pyoxidizer.bzl +file. Building from Rust is more involved, and requires multiple steps. +Please see the "PyOxidizer Rust Projects" section of the manual for more +information. + +The default configuration is to invoke a Python REPL. You can +edit the various pyoxidizer.*.bzl config files or the main.rs +file to change behavior. The application will need to be rebuilt +for configuration changes to take effect. +"#, + project_path = project_path.display() + ); Ok(()) }