What does rattler-build
do to build a package?#
rattler-build
creates conda packages which are relocatable packages.
These packages are built up with some rules and conventions in mind.
What goes into a package?#
Generally speaking, any new files that are copied into the $PREFIX
directory
at build time are part of the new package. However, there is some filtering
going on to exclude unwanted files, and noarch: python
packages have special
handling as well. The rules are as follows:
Filtering#
General File Filtering#
Certain files are filtered out to prevent them from being included in the package. These include:
- .pyo files: Optimized Python files are not included because they are considered harmful.
- .la files: Libtool archive files that are not needed at runtime.
- .DS_Store files: macOS-specific files that are irrelevant to the package.
- .git files and directories: Version control files, including
.gitignore
and the.git
directory, which are not needed in the package. - share/info/dir This file is ignored because it would be written from multiple packages.
Special Handling for noarch: python
Packages#
For packages marked as noarch: python
, special transformations are applied to
ensure compatibility across different platforms:
- Stripping Python Library Prefix: The "lib/pythonX.X" prefix is removed, retaining only the "site-packages" part of the path.
- Skipping
__pycache__
Directories and.pyc
Files: These are excluded and recreated during installation (they are specific to the Python version). - Replacing
bin
andScripts
Directories:- On Unix systems, the
bin
directory is replaced withpython-scripts
. - On Windows systems, the
Scripts
directory is replaced withpython-scripts
.
- On Unix systems, the
- Remove explicitly mentioned entrypoints: For
noarch: python
packages, entry points registered in the package are also taken into account. Files in thebin
orScripts
directories that match entry points are excluded to avoid duplications.
Symlink Handling#
Symlinks are carefully managed to ensure they are relative rather than absolute, which aids in making the package relocatable:
- Absolute symlinks pointing within the
$PREFIX
are converted to relative symlinks. - On Unix systems, this conversion is handled directly by creating new relative symlinks.
- On Windows, a warning is issued since symlink creation requires administrator privileges.
Making Packages Relocatable with rattler-build
#
Often, the most challenging aspect of building a package using rattler-build
is making it relocatable. A relocatable package can be installed into any
prefix, allowing it to be used outside the environment in which it was built.
This is in contrast to a non-relocatable package, which can only be utilized
within its original build environment.
rattler-build
automatically performs the following actions to make packages
relocatable:
- Binary object file conversion: Binary object files are converted to use
relative paths using
install_name_tool
on macOS andpatchelf
on Linux. This uses$ORIGIN
for elf files on Linux and@loader_path
for Mach-O files on macOS to make therpath
relative to the executable / shared library. - Text file prefix registration: Any text file without
NULL
bytes containing the placeholder prefix have the registered prefix replaced with the install prefix. - Binary file prefix detection and registration: Binary files containing
the build prefix can be automatically registered. The registered files will have
their build prefix replaced with the install prefix at install time. This works
by padding the install prefix with null terminators, such that the length of the
binary file remains the same. The build prefix must be long enough to
accommodate any reasonable installation prefix. On macOS and Linux,
rattler-build
pads the build prefix to 255 characters by appending_placehold
to the end of the build directory name.