diff --git a/Docs/source/developers/local_compile.rst b/Docs/source/developers/local_compile.rst new file mode 100644 index 00000000000..38e40d59f78 --- /dev/null +++ b/Docs/source/developers/local_compile.rst @@ -0,0 +1,89 @@ +.. _developers-local-compile: + +Fast, Local Compilation +======================= + +For simplicity, WarpX :ref:`compilation with CMake ` by default downloads, configures and compiles compatible versions of :ref:`central dependencies ` such as: + +* `AMReX `__ +* `PICSAR `__ +* `openPMD-api `__ +* `pyAMReX `__ +* `pybind11 `__ + +on-the-fly, which is called a *superbuild*. + +In some scenarios, e.g., when compiling without or with slow internet access or when working on WarpX and its dependencies, other strategies might be preferable. +In the below workflows, you as the developer need to make sure to use compatible versions of the dependencies you provide. + + +.. _developers-local-compile-src: + +Compiling From Local Sources +---------------------------- + +This workflow is best for developers that make changes to WarpX, AMReX, PICSAR, openPMD-api and/or pyAMReX at the same time. +For instance, use this if you add a feature in AMReX and want to try it in WarpX before it is proposed as a pull request for inclusion in AMReX. + +Instead of downloading the source code of the above dependencies, one can also use an already cloned source copy. +For instance, clone these three dependencies to ``$HOME/src``: + +.. code-block:: bash + + cd $HOME/src + + git clone https://github.com/ECP-WarpX/WarpX.git warpx + git clone https://github.com/AMReX-Codes/amrex.git + git clone https://github.com/openPMD/openPMD-api.git + git clone https://github.com/ECP-WarpX/picsar.git + git clone https://github.com/AMReX-Codes/pyamrex.git + git clone https://github.com/pybind/pybind11.git + +Now modify the dependencies as needed in their source locations, update sources if you cloned them earlier, etc. +When building WarpX, :ref:`the following CMake flags ` will use the respective local sources: + +.. code-block:: bash + + cd src/warpx + + rm -rf build + + cmake -S . -B build \ + -DWarpX_PYTHON=ON \ + -DWarpX_amrex_src=$HOME/src/amrex \ + -DWarpX_openpmd_src=$HOME/src/openPMD-api \ + -DWarpX_picsar_src=$HOME/src/picsar \ + -DWarpX_pyamrex_src=$HOME/src/pyamrex \ + -DWarpX_pybind11_src=$HOME/src/pybind11 + + cmake --build build -j 8 + + +.. _developers-local-compile-findpackage: + +Compiling With Pre-Compiled Dependencies +---------------------------------------- + +This workflow is best the fastest to compile WarpX, when you just want to change code in WarpX and have the above central dependencies already made available *in the right configurations* (e.g., w/ or w/o MPI or GPU support) from a :ref:`module system ` or :ref:`package manager `. + +Instead of downloading the source code of the above central dependencies, or using a local copy of their source, we can compile and install those once and instruct CMake to `find their install locations and configurations `__. + +WarpX supports this with :ref:`the following CMake flags `: + +.. code-block:: bash + + cd src/warpx + + rm -rf build + + cmake -S . -B build \ + -DWarpX_PYTHON=ON \ + -DWarpX_amrex_internal=OFF \ + -DWarpX_openpmd_internal=OFF \ + -DWarpX_picsar_internal=OFF \ + -DWarpX_pyamrex_internal=OFF \ + -DWarpX_pybind11_internal=OFF + + cmake --build build -j 8 + +As a background, this is also the workflow how WarpX is built in :ref:`package managers such as Spack and Conda-Forge `. diff --git a/Docs/source/developers/workflows.rst b/Docs/source/developers/workflows.rst index d56974b4101..8b357f5d4da 100644 --- a/Docs/source/developers/workflows.rst +++ b/Docs/source/developers/workflows.rst @@ -10,3 +10,4 @@ Workflows testing documentation checksum + local_compile diff --git a/Docs/source/install/cmake.rst b/Docs/source/install/cmake.rst index e299a60c75b..1f52b4f290f 100644 --- a/Docs/source/install/cmake.rst +++ b/Docs/source/install/cmake.rst @@ -147,10 +147,12 @@ Relative paths are also supported, e.g. ``-DWarpX_amrex_src=../amrex``. Or build against an AMReX feature branch of a colleague. Assuming your colleague pushed AMReX to ``https://github.com/WeiqunZhang/amrex/`` in a branch ``new-feature`` then pass to ``cmake`` the arguments: ``-DWarpX_amrex_repo=https://github.com/WeiqunZhang/amrex.git -DWarpX_amrex_branch=new-feature``. +More details on this :ref:`workflow are described here `. You can speed up the install further if you pre-install these dependencies, e.g. with a package manager. Set ``-DWarpX__internal=OFF`` and add installation prefix of the dependency to the environment variable `CMAKE_PREFIX_PATH `__. Please see the :ref:`introduction to CMake ` if this sounds new to you. +More details on this :ref:`workflow are described here `. If you re-compile often, consider installing the `Ninja `__ build system. Pass ``-G Ninja`` to the CMake configuration call to speed up parallel compiles. diff --git a/Docs/source/install/dependencies.rst b/Docs/source/install/dependencies.rst index a939db840da..94b2be78bec 100644 --- a/Docs/source/install/dependencies.rst +++ b/Docs/source/install/dependencies.rst @@ -12,6 +12,11 @@ Please see installation instructions below. - `AMReX `__: we automatically download and compile a copy of AMReX - `PICSAR `__: we automatically download and compile a copy of PICSAR +and for Python bindings: + +- `pyAMReX `__: we automatically download and compile a copy of pyAMReX +- `pybind11 `__: we automatically download and compile a copy of pybind11 + Optional dependencies include: - `MPI 3.0+ `__: for multi-node and/or multi-GPU execution