.. highlight:: console ============================ Development and contributing ============================ Setting up the development environment ====================================== 1. Clone the repository with :: git clone git@github.com:tfp-photonics/treams.git or :: git clone https://github.com/tfp-photonics/treams.git and enter the directory :: cd treams 2. This step is optional, but you might want to create an environment where treams and the development tools are created :: conda env create --name treams-dev python Activate the environment with:: conda activate treams-dev 3. Setup the package with :: pip install -e . This last step makes the program available in the environment independently of the current folder. This is especially necessary for correctly building the documentation. Running tests ============= To install the required packages for testing use :: pip install treams[test,coverage,io] Tests can be run using pytest with :: python -m pytest but for development a more fine grained selection can be made by passing a directory or file as an argument. Additionally, the option ``-k`` allows to define keywords when selecting test. Some integration tests for the module :ref:`generated/treams.lattice:treams.lattice` take a long time to finish and are therefore disabled by default. You can add them with the option ``--runslow``. If coverage reports should be included one can use the option ``--cov src/treams`` (which requires pytest-cov to be installed). However, this will only report on the pure python files. To also get coverage reports for the cython part, it is necessary to compile it with linetracing support. This can be achieved by setting the environment variable ``CYTHON_COVERAGE``, for example with :: CYTHON_COVERAGE=1 pip install -e . Make sure that new C code files are generated and that those files are compiled. Enabling the tracing for getting code coverage slows down the integration tests considerably. For the coverage calculation only the unit tests are used. Some test for importing and exporting need gmsh. These tests can be activated with ``--rungmsh`` analogous to the option ``--runslow`` above. Building the documentation ========================== To install the required packages for testing use :: pip install treams[docs] The documentation is built with sphinx by using :: sphinx-build -b html docs docs/_build/html from the root directory of the package to build the documentation as html pages. Some figures are automatically created, which requires matplotlib. The doctests can be run with :: sphinx-build -b doctest docs docs/_build/doctest Building the code on Windows ============================ The main issue with using treams on Windows is the compilation step. For Windows Python is usually compiled with MSVC for Visual Studio. However, especially for calculations with complex numbers, Cython creates code that conforms to the (C99-) standard. Thus, it is not compatible with the non-standard implementation of complex numbers by Microsoft. Below you find three tested ways, how one can use treams with Windows. The first two ways actually use a non-Windows version of Python, but have a more straightforward installation procedure. However, the last one works with Windows' version of Python e.g. when installed with conda under Windows. Windows Subsystem for Linux --------------------------- The `Windows Subsystem for Linux (WSL) `_ exists on recent versions of Windows. To install it, open the command line interpreter (cmd.exe) and type `wsl --install`. This step might be enough to be able to run a Linux kernel. Within WSL all instructions from the rest of the description can be used, e.g. with the distribution's Python or a conda-installed Python. Sometimes it is necessary to use `additional steps `_ to install WSL. Pure MSYS2 ---------- Using `MSYS2 `_, it is also possible to compile and install treams. First, install MSYS2 and update it according to the instructions. Then, also install python and, if you want, the dependencies of treams. Otherwise, the dependencies are installed by pip. Compilation with mingw-w64 -------------------------- This is approach is different from the others, since it finally combines binaries from two different compilers. Although it works and was tested on some systems, it is not guaranteed that it will work for all systems. The following part describes, how treams can be built for Windows. After installing MSYS2 use it to install ``mingw-w64-x86_64-gcc``. The compilation is steered from the command line. First go into the directory of treams. Then, set up your path by prepending the direction for MSYS2's mingw64 binaries with ``set PATH=C:\msys64\mingw64\bin;%PATH%`` (adjust accordingly if you have installed MSYS2 with non-default parameters). Check that gcc from MSYS2 is recognized correctly but make sure that the version of python that is found on the path corresponds to the Windows Python. With this setup, building binaries should work with `python -m build`. Continuous integration ====================== Using Github actions the steps above (building the documentation, running the doctests, running the tests with a coverage report, and building for all platforms) are implemented to run automatically on specific triggers. The relevant files in the ``.gihub/workflows`` directory can be also used as examples in addition to the description above.