=========================== Installation for developers =========================== Development environment ----------------------- To work on the source of Capytaine, it is recommended to use Conda_ (or the alternative implementation with the same user interface Mamba_) as package manager and virtual environment manager. Other Python package manager such as PDM_ can also be used. However Conda/Mamba can simplify the installation of some non-Python tools such as the Fortran compiler and will thus be used as example for the rest of this page. Please check also the section on Conda in the :doc:`user installation instructions `. .. _Conda: https://conda.io .. _Mamba: https://mamba.readthedocs.io/en/latest/ .. _PDM: https://pdm.fming.dev/latest/ Let us first `create a new virtual environment `_ with:: conda create --name capy_dev python pip conda activate capy_dev By default, Conda will install the latest version of Python. Capytaine requires Python 3.7 or higher, and is compatible with `all currently supported version of Python `_. Getting the source code ----------------------- If ``git`` is not available in your environment, you can install it through ``conda``:: conda install -c conda-forge git Then the source code can be downloaded using ``git`` with:: git clone https://github.com/capytaine/capytaine cd capytaine Alternatively, the source code can be directly downloaded from Github web interface. Getting a Fortran compiler -------------------------- Several options are available to get a Fortran compiler. Please choose below the most relevant to your case. .. collapse:: GFortran compiler on Linux or Windows Subsystem for Linux You can install ``gfortran`` with the package manager of your distribution. For instance on Debian or Ubuntu:: sudo apt install gfortran Alternatively, ``gfortran`` is also available from the ``conda-forge`` channel of the Conda package repository:: conda install -c conda-forge gfortran .. collapse:: GFortran compiler on macOS You can install ``gfortran`` via `Homebrew`_:: brew install gcc Make sure that the compilers installed by Homebrew are in you path (e.g., :code:`which gcc`); this can be accomplished by adding the relevant directories to your path:: export PATH="/usr/local/bin:$PATH" or through the use of aliases, e.g.,:: alias gcc=/usr/local/bin/gcc-10 .. _`Homebrew`: https://brew.sh .. collapse:: GFortran on Windows The GNU toolchain, including ``gfortran`` can be installed with the help of ``conda``:: conda install -c conda-forge m2w64-toolchain .. collapse:: Intel compiler on Windows Microsoft Visual Studio is required for linking the Fortran binaries * https://visualstudio.microsoft.com/downloads/ * During installation check the box to include :code:`Desktop development with C++` Intel oneAPI HPC toolkit is required for compiling the Fortran binaries (you do not need the base kit) * https://www.intel.com/content/www/us/en/developer/tools/oneapi/hpc-toolkit-download.html * Install to the default file location Create a ``LIB`` environment variable to point towards the intel directory for compiler ``.lib`` files * If oneAPI is installed to the default location, assign the LIB user variable a value of:: C:\Program Files (x86)\Intel\oneAPI\compiler\2022.1.0\windows\compiler\lib\intel64_win * If oneAPI is installed to a different location then adjust the path above as necessary Test if your Fortran compiler was installed correctly by entering :code:`ifort` on your command line Compiling and installing the code --------------------------------- The ``Makefile`` file in Capytaine repository contains short forms for the most common commands required to build Capytaine. If ``make`` is not available in your environment, you can install it through ``conda``:: conda install -c conda-forge make To compile the code and install it in the current environment, you can run:: make install which is just synonym of:: pip install . You can check that the package is installed by running:: python -c 'import capytaine as cpt; print(cpt.__version__)' or by checking the complete list of packages installed in the current environment with:: conda list .. note:: If you have an error of the form:: ModuleNotFoundError:: No module named 'capytaine.green_functions.libs.Delhommeau_float64' when importing Capytaine, it may be because the Python interpreter is trying to load the content of the local directory ``capytaine`` (containing only the source code) and not the actual compiled package. Running ``python`` from any other directory on your system should fix the issue, since there won't be a local ``capytaine`` directory to confuse the module importer. When using ``make install``, you will need to re-run the installation for any change made to the code to take effect in the installed version. For development, it is more convenient to use instead:: make develop Then all change made to the source code should automatically affects the installed package. (You may need to restard you Python interpreter.) Testing ------- To check that the installed packaged is working fine, you can run the test suite with Pytest. If Pytest is not already install, it can be done with:: pip install pytest Then run the following command from the root of Capytaine repository to test the code:: python -m pytest Alternatively, `Nox `_ can be used to set up an isolated environment and build and test the code. After installing Nox, use:: nox -s build_and_test_on_locked_env to test the current source code in an environment with fixed versions of Capytaine's dependencies, whereas:: nox -s build_and_test_on_latest_env will test the code in an environment using the latest available version of Capytaine's dependencies. Building the documentation -------------------------- TODO Contributing ------------ For instructions about how to help with the development of Capytaine, see the `contributing guide`_. .. _`contributing guide`: https://github.com/capytaine/capytaine/blob/master/CONTRIBUTING.md