From 7f75173c5a3edc6e8b60e4ebe3b0835370b8670f Mon Sep 17 00:00:00 2001 From: James Bruten Date: Tue, 28 Oct 2025 15:22:50 +0000 Subject: [PATCH 1/2] add local build instructions --- .../source/developer_guide/index.rst | 1 + .../source/developer_guide/local_builds.rst | 69 +++++++++++++++++++ 2 files changed, 70 insertions(+) create mode 100644 documentation/source/developer_guide/local_builds.rst diff --git a/documentation/source/developer_guide/index.rst b/documentation/source/developer_guide/index.rst index 3b6ea0d62..e8710f947 100644 --- a/documentation/source/developer_guide/index.rst +++ b/documentation/source/developer_guide/index.rst @@ -11,5 +11,6 @@ Developer Guide .. toctree:: :maxdepth: 2 + local_builds lfric_apps_rose_stem/index psyclone/index diff --git a/documentation/source/developer_guide/local_builds.rst b/documentation/source/developer_guide/local_builds.rst new file mode 100644 index 000000000..3fd34feb5 --- /dev/null +++ b/documentation/source/developer_guide/local_builds.rst @@ -0,0 +1,69 @@ +.. ----------------------------------------------------------------------------- + (c) Crown copyright Met Office. All rights reserved. + The file LICENCE, distributed with this code, contains details of the terms + under which the code may be used. + ----------------------------------------------------------------------------- + +LFRic Apps Command Line Builds +============================== + +The LFRic makefile build system is reliant on having code from both lfric_core +and lfric_apps available when launching, preventing the makefile from exporting +lfric_core as part of the build process. This introduces a circular dependency +in the makefile build system, not present when everything was on a single repo. +As the makefile system is planned to be replaced fab, it was decided to not +spend too much effort rewriting the makefiles and instead use a wrapper script +to export lfric_core and call the make command. + +The wrapper script is located at ``/build/local_build.py``. It is intended that +all command line options available in the makefile system can be used here - if +any have been missed then as it's a python file it should be easily extendable. +The script can be launched from anywhere by calling it, eg: + +``./local_build.py `` + +where ``PROJECT`` is the name of the LFRic Apps project being built, eg. +``gungho_model``. This can be an application, science or interface section, +although some of these may only contain a subset of possible make targets. The +``PROJECT`` is always required. The script has been setup to behave as the old +make system did. It will create a ``working`` and a ``bin`` dir inside the +project directory by default. Its first step is to export the lfric_core repo +and then rsync it to the working dir so that incremental builds continue to +work. + +At the Met Office you will need to load the lfric environments before starting +the script. + +This table lists the command line arguments available: + ++----------------------+-----------------------------------------------------------+ +| *Option* | *Default* | *Description* | ++======================+=============================+=============================+ +| ``-c --core_source`` | If not provided, the script | The lfric_core source | +| | will parse the | being used. Can be a | +| | ``dependencies.yaml`` file | remote github repository | +| | and use the core source set | or a local clone. | +| | there. | | ++----------------------+-----------------------------+-----------------------------+ +| ``-w --working_dir`` | The project directory. | The working directory | +| | | for the build process. | ++----------------------+-----------------------------+-----------------------------+ +| ``-j --ncores`` | 4 | Integer, the number of | +| | | cores for the build task | ++----------------------+-----------------------------+-----------------------------+ +| ``-t --target`` | build | The makefile target, eg. | +| | | build, unit-tests, clean | ++----------------------+-----------------------------+-----------------------------+ +| ``-o --optlevel`` | None, Uses the default set | The optimisation level | +| | in the makefile, usually | of the build process. | +| | ``fast-debug``. | | ++----------------------+-----------------------------+-----------------------------+ +| ``-p --psyclone`` | None, Uses the default set | Value passed to the | +| | in the makefile. | ``PSYCLONE_TRANSFORMATION`` | +| | | variable in the makefile. | ++----------------------+-----------------------------+-----------------------------+ +| ``-v --verbose`` | None, or "off" | Supplying this argument, | +| | | which takes no argument, | +| | | will request verbose output | +| | | from the makefile. | ++----------------------+-----------------------------+-----------------------------+ From 0bcad755d19fd55a56bf5bd934ce163d2fb931f2 Mon Sep 17 00:00:00 2001 From: James Bruten <109733895+james-bruten-mo@users.noreply.github.com> Date: Tue, 28 Oct 2025 16:48:06 +0000 Subject: [PATCH 2/2] Update documentation/source/developer_guide/local_builds.rst Co-authored-by: allynt --- documentation/source/developer_guide/local_builds.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/source/developer_guide/local_builds.rst b/documentation/source/developer_guide/local_builds.rst index 3fd34feb5..9e5bd9310 100644 --- a/documentation/source/developer_guide/local_builds.rst +++ b/documentation/source/developer_guide/local_builds.rst @@ -11,7 +11,7 @@ The LFRic makefile build system is reliant on having code from both lfric_core and lfric_apps available when launching, preventing the makefile from exporting lfric_core as part of the build process. This introduces a circular dependency in the makefile build system, not present when everything was on a single repo. -As the makefile system is planned to be replaced fab, it was decided to not +As the makefile system is planned to be replaced by fab, it was decided to not spend too much effort rewriting the makefiles and instead use a wrapper script to export lfric_core and call the make command.