From 0c7c1c8bd5c294db86a1a85314fd964852c14593 Mon Sep 17 00:00:00 2001 From: Dan Padilha Date: Fri, 19 Jul 2024 08:20:59 +0000 Subject: [PATCH] Added pip installation documentation and release notes. --- docs/source/Install.rst | 1 + docs/source/Install/pipInstall.rst | 125 ++++++++++++++++++++++++ docs/source/Support/bskKnownIssues.rst | 2 + docs/source/Support/bskReleaseNotes.rst | 5 + 4 files changed, 133 insertions(+) create mode 100644 docs/source/Install/pipInstall.rst diff --git a/docs/source/Install.rst b/docs/source/Install.rst index 7ce0fa128b..0072cffbbb 100644 --- a/docs/source/Install.rst +++ b/docs/source/Install.rst @@ -21,6 +21,7 @@ Install Install/installOptionalPackages Install/customPython Install/installBuildConan + Install/pipInstall diff --git a/docs/source/Install/pipInstall.rst b/docs/source/Install/pipInstall.rst new file mode 100644 index 0000000000..9d32a584da --- /dev/null +++ b/docs/source/Install/pipInstall.rst @@ -0,0 +1,125 @@ +.. toctree:: + :hidden: + +.. _pipInstall: + +Advanced: Building and installing pre-compiled Basilisk wheels +============================================================== + +.. warning:: + + This method of building Basilisk is currently Work-In-Progress, and should only be attempted by advanced users + familiar with `Python packaging and distribution + `_. + This method is not yet guaranteed to work on every platform, and there are still some annoyances + to iron out, but we appreciate any feedback you may have. + + Most users should see :ref:`configureBuild` for documentation on the regular build process. + + +Building & Installing with ``pip`` +---------------------------------- + +.. note:: + + All commands are called from the Basilisk root directory. + +Basilisk can be built and installed using standard Python packaging tools[#f1] such as ``pip``. +The simplest usage is:: + + pip install -v . + +This command compiles and installs Basilisk into the user's current Python environment. (Note: the ``-v`` flag is +added to display verbose compilation messages, otherwise it can look like the installation process is stuck.) + +Build options (as passed to ``conanfile.py`` and described in :ref:`configureBuild`) can be provided using the +``CONAN_ARGS`` environment variable:: + + CONAN_ARGS="--pathToExternalModules='/path/to/external' --opNav True" pip install -v . + +.. warning:: + + For backwards compatibility reasons, and due to issues arising from temporary build environments, editable + installations (``pip install -e .``) are not currently supported. Please follow the standard + :ref:`configureBuild` process. + +On its own, there is no significant benefit to installing Basilisk in this way. However, supporting standard Python +packaging tools means that Basilisk can now be built into a pre-compiled `"wheel" (.whl) file +`_ that can be shared +and installed on other compatible machines. + +Using ``pip``, the command below will generate a ``Basilisk-*.whl`` file in the current directory:: + + pip wheel --no-deps -v . + +The resulting wheel file can then be installed using ``pip``:: + + pip install Basilisk-*.whl + +The main benefit of this approach will come in the future, when a set of pre-compiled wheels will be made available, +allowing most users to easily ``pip install Basilisk`` without compilation, in the same way that packages like +``numpy``, ``scipy``, and ``pandas`` are available. + + +Wheel Compatibility +------------------- + +.. warning:: + + Wheel compatibility is currently being verified across Python versions and different platforms. So far, + some users have reported successfully installing the same wheel on different Ubuntu versions and with + different Python versions, but your mileage may vary. + + If you choose to try this feature and run into and problems, please `raise an issue + `_ for the Basilisk maintainers to investigate. + +When installed using a standard Python packaging tool such as ``pip``, Basilisk will automatically be +built using the `Python Limited C API `_. The +resulting wheel file will contain a set of compiled Python extension modules that, at least in theory, can be +run using any compatible Python version (currently, any Python 3.8+). + +To maintain backwards compatibility, standard Basilisk installations via ``python conanfile.py`` are not +compatible between different Python versions, as is stated in :ref:`customPython`. However, users can +also forcibly build with the Python Limited C API by providing the ``--pyLimitedAPI`` flag:: + + python conanfile.py --pyLimitedAPI 0x030800f0 + + +For Maintainers: Overview of Implementation +------------------------------------------- + +Python packaging support is provided through the ``pyproject.toml`` file as specified by the `PEP-517 +`_ standard. This file defines the desired "back-end" tool used to build +Basilisk, as well as other packaging settings including which Python packages are required for building +and running Basilisk. + +At the time of this writing, the build backend is ``setuptools``, which invokes the ``setup.py`` file to +perform the build. In ``setup.py``, the Python extension builder is overridden with a custom builder that +computes an appropriate Python Limited C API version (based on the minimum supported Python version +specified in ``pyproject.toml``). The builder then invokes ``python conanfile.py``, setting the +``--managePipEnvironment False`` option so that Conan does not directly manipulate the user's ``pip`` +environment. The main reasons for this setting was to maintain the current default behaviour of +``conanfile.py``-based installation. + +Editable installations (i.e. ``pip install -e .``) are not currently supported for two main reasons: + +1. ``pip install -e .`` is currently overridden to maintain the existing ``python conanfile.py`` behaviour. +2. Due to the underlying CMake build system, editable installs with ``pip`` require setting the + ``--no-build-isolation`` option, which means that the user must manually install the build requirements. + Since these build requirements are installed automatically by the standard ``conanfile.py`` installation, + it is the recommended method for editable installations. + +Tools such as `cibuildwheel `_ can be used to build wheels that are +automatically compatible with a broad range of operating system versions. These pre-compiled wheels can then +be shared publicly using tools like `twine `_ to upload them to the +`Python Package Index (PyPi) `_, allowing users to simply ``pip install Basilisk``. We +expect that these tools will be added into the Basilisk Continuous Integration pipeline in the future. + +Further discussions and implementation details can be found in +`Basilisk merge request #737 `_. + + +.. rubric:: Footnotes + +.. [#f1] "Standard Python packaging tools" are those which comply with modern Python packaging standards + such as `PEP-517 `_. \ No newline at end of file diff --git a/docs/source/Support/bskKnownIssues.rst b/docs/source/Support/bskKnownIssues.rst index e07e96e48a..ab5a1ecdbe 100644 --- a/docs/source/Support/bskKnownIssues.rst +++ b/docs/source/Support/bskKnownIssues.rst @@ -12,6 +12,8 @@ Version |release| ----------------- - The fuel tank models have become classes and python simulation code using tank modules need to be updated. See :ref:`fueltank` or :ref:`scenarioFuelSlosh` for further documentation. +- pip-based installation in editable mode using `pip install -e .` is not currently supported. + Developers and users alike should continue to use `python conanfile.py` installation. Version 2.3.0 diff --git a/docs/source/Support/bskReleaseNotes.rst b/docs/source/Support/bskReleaseNotes.rst index 84f848cf44..6ffdd2a4c9 100644 --- a/docs/source/Support/bskReleaseNotes.rst +++ b/docs/source/Support/bskReleaseNotes.rst @@ -27,6 +27,7 @@ Basilisk Release Notes - spacecraft charging related modules - support a way to do thread-safe messaging - automated documentation build system when code is pushed to the repo + - `pip`-based installation and pre-compiled releases Version |release| @@ -69,6 +70,10 @@ Version |release| gracefull module variable depreciation if needed. - Added support for numpy 2.0. - Fixed use of spherical coordinate system in :ref:`magneticFieldWMM` model. +- Added PEP-517-compliant project specification, providing initial support for installation via `pip install .`. + + - NOTE: This is primarily intended to support pre-compiled releases in the future. All users are recommended to continue + using `python conanfile.py` installation for now. Version 2.3.0 (April 5, 2024)