Skip to content

Commit 46dc7a0

Browse files
Jonathanlyjwkliao
authored andcommitted
add notes about wheel and source distribution
1 parent 99bca67 commit 46dc7a0

File tree

1 file changed

+14
-0
lines changed

1 file changed

+14
-0
lines changed

DEVELOPER_NOTES.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,20 @@
1818
CC=/path/to/mpicc PNETCDF_DIR=/path/to/pnetcdf/dir pip install dist/package-<version>.tar.gz
1919
```
2020
5. Check installation by test and example programs
21+
* More notes about quick install
22+
1. Source distribution(.tar.gz)
23+
* Pip-install command’s second go-to option if no matching build distribution is found on PyPI. It will build its own wheel file for the current system. For python libs with C-extension (like pnetcdf-python, netcdf4-python, h5py), wheel installation require their C bindings.
24+
* Invariant to platforms/versions, usually each version of python library has one single source distribution.
25+
2. Build distribution (.whl)
26+
* Pip-install command’s first go-to option by default. For python libs with C-extension (like pnetcdf-python, netcdf4-python, h5py), wheel installation does not require their C bindings.
27+
* Wheels are platform-specific and python-version specific. Different system used for building and uploading will generate different versions of wheel files on PyPI. To cover most mainstream python versions and operating systems, python libraries (like [numpy 1.25](https://pypi.org/project/numpy/#files)) has 20+ wheels files to cover most mainstream systems (e.g. Linux (x86_64), macOS (x86_64), and Windows (32-bit and 64-bit)) and recent python versions.
28+
* General procedures of building and uploading python library wheels (build distributions) for MacOS and Linux systems
29+
* Python libs with C-extension (like pncpy, netcdf4-python, h5py) requires shared object (.so in linux and .dylibs in mac) files collected from C software installation. When making python library wheels (build distribution), an extra post-processing step (Delocate tool for Mac, auditwheel Tool in linux) is usually performed to copy and store these files in the python package to remove these dependencies. That’s why the user’s pip install with build distribution does not require a C installation as a prerequisite.
30+
* For MacOS wheels (like netCDF4-1.6.4-cp311-cp311-macosx_10_9_x86_64.whl), need to: Build the package to create the wheel -> Use Delocate tool to fix wheels -> Upload to PyPI.
31+
* For Linux wheels, need to: Pull manylinux docker image -> build the package to create the wheel in this container -> Use auditwheel Tool to fix wheels -> Upload to PyPI.
32+
* For some python libraries (numpy, netCDF4), a [dedicated github repo](https://github.com/MacPython/netcdf4-python-wheels) is used to automate building wheels for every release.
33+
34+
2135
* Developer install
2236
* Developer installation is mainly managed by `setup.py` and `pyproject.toml`. The former one is the core file to build the package and the latter manages dependencies required by `pip install` command.
2337
* `python setup.py install` builds and installs the python library based on the current python environment and will error out if dependency (e.g. mpi4py) not met. This command is going to be deprecated and is not recommended for modern python library installation.

0 commit comments

Comments
 (0)