The pyoxidizer
Command Line Tool¶
The pyoxidizer
command line tool is a frontend to the various
functionality of PyOxidizer
. See Components for more
on the various components of PyOxidizer
.
Creating New Projects with init-config-file
¶
The pyoxidizer init-config-file
command will create a new
pyoxidizer.bzl
configuration file in the target directory:
$ pyoxidizer init-config-file pyapp
This should have printed out details on what happened and what to do next.
Creating New Rust Projects with init-rust-project
¶
The pyoxidizer init-rust-project
command creates a minimal
Rust project configured to build an application that runs an
embedded Python interpreter from a configuration defined in a
pyoxidizer.bzl
configuration file. Run it by specifying the
directory to contain the new project:
$ pyoxidizer init-rust-project pyapp
This should have printed out details on what happened and what to do next.
The explicit creation of Rust projects to use PyOxidizer
is not
required. If your produced binaries only need to perform actions
configurable via PyOxidizer
configuration files (like running
some Python code), an explicit Rust project isn’t required, as
PyOxidizer
can auto-generate a temporary Rust project at build time.
But if you want to supplement the behavior of the binaries built with Rust, an explicit and persisted Rust project can facilitate that. For example, you may want to run custom Rust code before, during, and after a Python interpreter runs in the process.
See Rust Projects for more on the composition of Rust projects.
Adding PyOxidizer to an Existing Project with add
¶
Do you have an existing Rust project that you want to add an embedded
Python interpreter to? PyOxidizer can help with that too! The
pyoxidizer add
command can be used to add an embedded Python
interpreter to an existing Rust project. Simply give the directory
to a project containing a Cargo.toml
file:
$ cargo init myrustapp
Created binary (application) package
$ pyoxidizer add myrustapp
This will add required files and make required modifications to add an embedded Python interpreter to the target project.
Important
It is highly recommended to have the destination project under version
control so you can see what changes are made by pyoxidizer add
and
so you can undo any unwanted changes.
Danger
This command isn’t very well tested. And results have been known to be
wrong. If it doesn’t just work, you may want to run pyoxidizer init
and incorporate relevant files into your project manually. Sorry for
the inconvenience.
Building PyObject Projects with build
¶
The pyoxidizer build
command is probably the most important and used
pyoxidizer
command. This command evaluates a pyoxidizer.bzl
configuration file by resolving targets in it.
By default, the default target in the configuration file is resolved. However, callers can specify a list of explicit targets to resolve. e.g.:
# Resolve the default target.
$ pyoxidizer build
# Resolve the "exe" and "install" targets, in that order.
$ pyoxidizer build exe install
PyOxidizer
configuration files are effectively defining a build
system, hence the name build for the command to resolve targets
within.
Running the Result of Building with run
¶
Target functions in PyOxidizer
configuration files return objects
that may be runnable. For example, a
PythonExecutable returned by a target
function that defines a Python executable binary can be run by
executing a new process.
The pyoxidizer run
command is used to attempt to run an object
returned by a build target. It is effectively pyoxidizer build
followed
by running the returned object. e.g.:
# Run the default target.
$ pyoxidizer run
# Run the "install" target.
$ pyoxidizer run --target install
Analyzing Produced Binaries with analyze
¶
The pyoxidizer analyze
command is a generic command for analyzing the
contents of executables and libraries. While it is generic, its output is
specifically tailored for PyOxidizer
.
Run the command with the path to an executable. For example:
$ pyoxidizer analyze build/apps/myapp/x86_64-unknown-linux-gnu/debug/myapp
Behavior is dependent on the format of the file being analyzed. But the
general theme is that the command attempts to identify the run-time
requirements for that binary. For example, for ELF binaries it will
list all shared library dependencies and analyze glibc
symbol
versions and print out which Linux distributions it thinks the binary
is compatible with.
Note
pyoxidizer analyze
is not yet implemented for all executable
file types that PyOxidizer
supports.
Inspecting Python Distributions¶
PyOxidizer
uses special pre-built Python distributions to build
binaries containing Python.
These Python distributions are zstandard compressed tar files. Zstandard
is a modern compression format that is really, really, really good.
(PyOxidizer’s maintainer also maintains
Python bindings to zstandard
and has
written about the benefits of zstandard
on his blog. You should read that blog post so you are enlightened on
how amazing zstandard is.) But because zstandard is relatively new, not
all systems have utilities for decompressing that format yet. So, the
pyoxidizer python-distribution-extract
command can be used to extract
the zstandard compressed tar archive to a local filesystem path.
Python distributions contain software governed by a number of licenses. This of course has implications for application distribution. See Licensing Considerations for more.
The pyoxidizer python-distribution-licenses
command can be used to
inspect a Python distribution archive for information about its licenses.
The command will print information about the licensing of the Python
distribution itself along with a per-extension breakdown of which
libraries are used by which extensions and which licenses apply to what.
This command can be super useful to audit for license usage and only allow
extensions with licenses that you are legally comfortable with.
For example, the entry for the readline
extension shows that the
extension links against the ncurses
and readline
libraries, which
are governed by the X11, and GPL-3.0 licenses:
readline
--------
Dependency: ncurses
Link Type: library
Dependency: readline
Link Type: library
Licenses: GPL-3.0, X11
License Info: https://spdx.org/licenses/GPL-3.0.html
License Info: https://spdx.org/licenses/X11.html
Note
The license annotations in Python distributions are best effort and can be wrong. They do not constitute a legal promise. Paranoid individuals may want to double check the license annotations by verifying with source code distributions, for example.