DISTRIBUTE

Building spacepy for distribution (20240306)
============================================
Since this has to happen on multiple platforms, a single script doesn't work.

Prepare the release commit
--------------------------

Go through this process for a release candidate and upload to test
PyPI first (https://www.python.org/dev/peps/pep-0440/#pre-releases)
and, once final build is ready, also check it on test PyPI.

Edit the release notes to include the release date.

The following changes should result in either the final release version,
or the appropriate release candidate (i.e. add "rc1" if building rc).
Edit Doc/source/conf.py. Around line 128, remove (DRAFT) from the title.
    Change version around line 72 (two places!)
Change version in setup.py, in setup_kwargs near bottom.
Change __version__ around line 209 of __init__.py.
Edit pyproject.toml around line 18 to change version.

Commit these changes. Submit PR. (Tagging is done on github now.)

Miniconda setup
---------------
Download/install the latest miniconda into some appropriate place
on the machine where you'll do the source build, e.g.:
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash ./Miniconda3-latest-Linux-x86_64.sh -b -p ~/miniconda

(See also developer/scripts/test_all.sh for some details).

If CDF library isn't installed, download/install CDF, so that the pycdf
library will import and the docs build:
wget https://spdf.gsfc.nasa.gov/pub/software/cdf/dist/cdf38_0/linux/cdf38_0-dist-cdf.tar.gz; tar xzf cdf38_0-dist-cdf.tar.gz; pushd cdf38_0-dist; make OS=linux ENV=gnu all; make INSTALLDIR=$HOME/cdf install; popd
source ${HOME}/cdf/bin/definitions.B

Make a clean isolated environment just for SpacePy build:
~/miniconda/bin/conda create -y -n spacepy_build python=3
source ~/miniconda/bin/activate spacepy_build
conda install -y pip python-build wheel
conda install -y numpy
conda install -y scipy matplotlib h5py astropy sphinx numpydoc

(Use "conda deactivate" when done, but not done yet...))

Prepare the source build
------------------------

On a Unix machine:
Activate the conda environment, if necessary.

check out the latest from git (hopefully the release commit!)

Clear out old builds:
    rm -rf build/ Doc/build/ Doc/source/autosummary/

Be sure that LD_LIBRARY_PATH and similar aren't set so that the conda
environment isn't pulling in anything from the host environment.

    PYTHONNOUSERSITE=1 PYTHONPATH= python-build -s -n -x

(We are only building the source distribution, do not want an isolated
build environment because already installed the dependencies, and are
similarly skipping the dependency check...particularly because the
dependencies for the source build and binary build are different but
build doesn't support that.)

The resulting .tar.gz is in the dists directory.

Install so getting the latest inputs for the autodocs:
    PYTHONNOUSERSITE=1 PYTHONPATH= pip install --no-build-isolation --no-deps .
(This is subject to future review to support installing in a temporary
location.)

Build the docs:
    cd Doc
    PYTHONNOUSERSITE=1 PYTHONPATH= make html
    PYTHONNOUSERSITE=1 PYTHONPATH= make latexpdf
Newer sphinx uses latexmk (apt-get install latexmk) not pdflatex...

Note: Building the source distribution will not build the docs, this
needs to be done manually so they can be uploaded separately later.

Prepare the Windows binaries
----------------------------

Unzip the source distribution from the Unix side. Get the Windows
build scripts from the repository. They're in developer/scripts but
are not included in the source distribution. They need to be put in
developer/scripts in the unzipped source so they can find the rest of
SpacePy. Yes this could be improved.

Download the CDF library and extract the DLL. This is easiest done on
the Unix side and then transferred over--it just needs to be in the
top-level directory with setup.py.
    wget https://spdf.gsfc.nasa.gov/pub/software/cdf/dist/cdf39_1/windows/cdf3.9.1_64bit_WinZip_Installer.zip
    unzip -j cdf3.9.1_64bit_WinZip_Installer.zip bin/dllcdf.dll

Download latest 64-bit Miniconda from
https://docs.conda.io/en/latest/miniconda.html and put it in the
user-default download directory (%USERPROFILE%\Downloads)

MSVC needs to be installed from
https://visualstudio.microsoft.com/visual-cpp-build-tools/ before
making the Python 3.12 environment, and should be uninstalled
after. This can be done before building the entire Windows build
system (following) or by separating out the 3.12 work.

Run the rest of the process in a command prompt with administrator
access so that Miniconda can be installed to a reasonable location--if
it is installed to the user's directory, there's often a space there,
and that confuses f2py.

Set up conda environments for the build by running
"win_build_system_setup.cmd build". This will make conda environments
and install the earliest supported version of numpy in each. Then run
build_win.cmd to make Windows binaries and wheels, and
win_build_system_teardown.cmd to remove those environment (and
miniconda). Windows binaries and wheels will be in the "dist"
directory of the SpacePy distribution.

There may be a console error "This application has requested the
Runtime to terminate it in an unusual way" with a popup "python.exe
has stopped working." This doesn't seem to be a problem, just click
"Close the program" in the popup.

Making Mac binaries
-----------------------------
Assumes miniconda is in ~/opt/miniconda. E.g. download the "bash" (.sh), install for me only, do not change install location
sh ./Miniconda3-latest-MacOSX-x86_64.sh -b -p ~/opt/miniconda/

conda only has gfortran 11.2 and 11.3. 11.2 installs libgfortran-5.0.0, so may have a limitation on what C library that gets compiled against. In the future check https://stackoverflow.com/questions/17910684/static-libgfortran-in-library-build

Download the CDF library; need to build from source since they compile against a new SDK. You can check this at https://stackoverflow.com/questions/17143373/determine-minimum-osx-version-a-binary-was-compiled-for
Do this build WITHOUT having conda loaded (so we don't get the wrong ld)

curl https://spdf.gsfc.nasa.gov/pub/software/cdf/dist/cdf39_1/macosx/src_distribution/cdf39_1-dist-cdf.tar.gz --output cdf39_1-dist-cdf.tar.gz
tar -zxvf cdf39_1-dist-cdf.tar.gz
cd cdf39_1-dist
# So we can override this later
sed -i '' 's/LDLIB=-L\$(XCODEDir)/LDLIB?=-L\$(XCODEDir)/' Makefile
# if you need real xcodeversion, use this, but "10.2" gets the new codepath
# pkgutil --pkg-info=com.apple.pkg.CLTools_Executables
# For Apple Silicon
SDKROOT=/opt/MacOSX11.0.sdk make XCODEVERSION=10.2 LDLIB=-L/opt/MacOSX11.0.sdk/usr/lib OS=macosx ENV=arm64 SHARED=yes CURSES=no FORTRAN=no all
# For Intel
SDKROOT=/opt/MacOSX10.9.sdk make XCODEVERSION=10.2 LDLIB="-L/opt/MacOSX10.9.sdk/usr/lib -L/opt/MacOSX10.9.sdk/usr/lib/system" OS=macosx ENV=x86_64 SHARED=yes CURSES=no FORTRAN=no all

Unzip the spacepy source distribution made above into another directory. Copy
over the developer/scripts/mac_x86_wheels.sh script into that directory
(top-level is fine, next to setup.py) and also copy in the final compiled CDF library (src/lib/libcdf.dylib) Run:
    zsh ./mac_x86_wheels.sh

The binary wheels will be in the "dist" directory. Do this whole process for both x86 and ARM (mac_arm_wheels.sh).

Making Linux binaries
-----------------------------
Information on cross-distro compatibility is at:
https://peps.python.org/pep-0513/
https://peps.python.org/pep-0599/
https://peps.python.org/pep-0600/
https://github.com/pypa/manylinux
https://github.com/pypa/auditwheel/tree/main
https://quay.io/organization/pypa
http://www.martin-rdz.de/index.php/2022/02/05/manually-building-manylinux-python-wheels/

We build to manylinux2014_x86_64 since that's the oldest currently supported; that's roughly Ubuntu 20.04 and CentOS 7.

sudo aptitude install docker.io
sudo usermod -aG docker USERNAME
docker run -i -t --rm -v `pwd`:/io quay.io/pypa/manylinux2014_x86_64 /bin/bash /io/developer/scripts/manylinux_wheels.sh

Need to change owner of the wheels after they're copied out, in the future can try running docker with --user $(id -u):$(id -g) but then will need to work with write permissions for the pip installs inside the container.

Fixing wheel metadata version
-----------------------------

Wheels are built with metadata 2.1. Support for this was included in
setuptools 38.0 (SpacePy requires 44.1.1) and wheel 0.31.0
(0.34.2). The pip changelog doesn't note when this support was added,
but 10.0 came out about the same time as wheel 0.31.0, and we require
20.0.2. build had no releases before 2020; wheel 0.31 was released and
PEP 566 accepted in 2018. So we no longer need to roll back to
metadata 2.0 and can use 2.1 directly.

General notes on binaries
-------------------------

It looks like the wheels are compatible across Windows versions,
i.e. a wheel built on Windows 10 seems to install okay in Windows 7,
which is great.

Using the oldest supported numpy for the build is used for ABI
compatibility for the f2py-built extensions (irbem mostly). See
https://github.com/numpy/numpy/issues/5888. It looks like there isn't
a way to specify the ABI version in f2py so the only answer is to
compile with an old-enough numpy. In particular there's a note "SciPy
pins its build system to the oldest numpy it wishes to support".

ABI is in numpy/core/setup_common.py and there's no history, so going
through the git tags for each numpy release gives:

1.4 through current main : 0x01000009

It looks like ABI version is a complete break: if it changes, old
modules will no longer work. However, the API version is backward
compatible: any version with a particular API version can be used on
anything with the same API version (even older numpy versions) or
newer, provided ABI version is the same. There's a list in
numpyconfig.h but it disagrees with the history given in
setup_common.py; they are probably used for slightly different
purposes. History going through commits of setup_common.py is:

1.10.0, 1.11.0, 1.12.0: 0x0000000a
1.13.0: 0x0000000b
1.14.0, 1.15.0: 0x0000000c
1.16.0, 1.17.0, 1.18.0, 1.19.0: 0x0000000d
1.20.0, 1.21.0: 0x0000000e

The list in the latest setup_common.py is incomplete (it seems to
imply that gaps are filled with the same value.)


Docs
----

From the Doc directory:
cp build/latex/SpacePy.pdf spacepy-x.y.z-doc.pdf
cd build/html
zip -r ../../spacepy-0.2.1-doc.zip *

Test PyPI
---------

https://packaging.python.org/guides/using-testpypi/

Consider https://www.python.org/dev/peps/pep-0440/#pre-releases

Make a .pypirc file, see https://docs.python.org/3.3/distutils/packageindex.html

[distutils]
index-servers =
    pypi
    testpypi

[pypi]
username: <username>

[testpypi]
repository: https://test.pypi.org/legacy/
username: <username>

(end of .pypirc)

Put all the builds (wheels, source dists, not the docs) into one
directory. Use the spacepy_build conda environment and install twine:

  source ~/miniconda/bin/activate spacepy_build
  conda install twine

and then do the upload:
To do the upload, you need to authenticate with an API token, see https://test.pypi.org/help/#apitoken

  PYTHONNOUSERSITE=1 PYTHONPATH= twine upload -r testpypi spacepy-*.whl spacepy-*.tar.gz

PyPI does not support Windows standalone installers, and can only take
one source distribution (zip or tar.gz); build seems to prefer the tarball.

Test installing with:

  pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ spacepy

Do this on Windows without compilers installed, and in a clean Linux
Anaconda env. You can use the --pre flag to install the RC version; in
that case, probably want to use --no-deps so don't get RC version of
dependencies! (Or can specify the rc version, e.g. spacepy==0.2.2rc1).

Release to PyPI
---------------

https://python-packaging-tutorial.readthedocs.io/en/latest/uploading_pypi.html

  twine upload spacepy-*-doc.zip spacepy-*.whl spacepy-*.tar.gz

Do not make or upload a .zip sdist since can only upload one source
package per release.

There's no longer any capability to edit information on PyPI, it's
straight from the setup.py metadata. This may cause problems with the
fact that we're CamelCase on PyPI...

Release to github
-----------------

https://help.github.com/en/articles/creating-releases

On the code tab, click on "n releases" (on the right column, below
"about"). Click "Draft a new release." Make the tag
"release-x.y.z" and hopefully the target will be main if it's up to
date. The most consistent with what we've done so far (which is not
necessarily the best) is to use just "x.y.z" as the title with nothing
the "describe."

Click in the "upload binaries" area and upload all the files: source
distribution tar.gz, wheels, documentation PDF (spacepy-x.y.z-doc.pdf)
and a zip (spacepy-x.y.z-doc.zip).

Documentation update
--------------------

Check out the spacepy.github.io repository. Right now the root of the
repo is basically the root of the Doc/build/html output. Copy all the
freshly-built docs there, commit, submit PR.

Relevant notes
--------------

Reference that have been useful for putting the wheels together (this
can eventually be captured elsewhere.)

https://www.python.org/dev/peps/pep-0427/
https://pip.pypa.io/en/stable/reference/pip_wheel/
https://docs.python.org/2/library/sysconfig.html#installation-paths
https://github.com/dask/hdfs3/issues/113
https://python-packaging-tutorial.readthedocs.io/en/latest/uploading_pypi.html
https://packaging.python.org/tutorials/packaging-projects/

Wheel is a separate package but seems to be included with
miniconda. (It's not just pip or setuptools, but it might be a
requirement for pip? Although not installed on Linux with pip.)

https://stackoverflow.com/questions/45150304/how-to-force-a-python-wheel-to-be-platform-specific-when-building-it