diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index cec74459a7e882300284098f4f19667f6cd8e75a..c80ff2c508d928ce9770c722fcc9d6d16bf6eece 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -1663,7 +1663,7 @@ platform:debian:bullseye: - .platform-test variables: CONFIGURE_FLAGS: "--disable-swig-octave --enable-python --enable-swig-python" - ENVIRONMENT_FILE: "conda/environment.yml" + ENVIRONMENT_FILE: "common/conda/environment.yml" before_script: # configure conda - source ${CONDA_ROOT:-/opt/conda}/etc/profile.d/conda.sh @@ -1970,7 +1970,7 @@ lint:depends: python-debian python-rpm-spec script: - - ./gnuscripts/check_library_dependencies + - ./common/maintainer-scripts/check_library_dependencies lint:gitignore: extends: diff --git a/.gitlab/CODEOWNERS b/.gitlab/CODEOWNERS index 19942c0ffb972bcc5a21dd3f68de7c719628fb89..9f8331d97f9a0c55378dbe6c970072d790b9dd47 100644 --- a/.gitlab/CODEOWNERS +++ b/.gitlab/CODEOWNERS @@ -41,7 +41,6 @@ Makefile.am @adam-mercer @duncanmmacleod @karl-wette conda/ @adam-mercer @duncanmmacleod @karl-wette configure.ac @adam-mercer @duncanmmacleod @karl-wette debian/ @adam-mercer @duncanmmacleod @karl-wette -docker/ @adam-mercer @duncanmmacleod @karl-wette doxygen/ @adam-mercer @duncanmmacleod @karl-wette gnuscripts/ @adam-mercer @duncanmmacleod @karl-wette include/ @adam-mercer @duncanmmacleod @karl-wette diff --git a/README.md b/README.md index 52214a60679b87399ad299736736b313e012627e..1a2105ff381edcd232abe48e1608895591883054 100644 --- a/README.md +++ b/README.md @@ -47,11 +47,11 @@ repository. It can then be cloned using: ## Building from Source The recommended way to build LALSuite from source is in a `conda` environment. -[A recipe file](conda/environment.yml) is available with all main dependencies. +[A recipe file](common/conda/environment.yml) is available with all main dependencies. This can serve as the base for custom recipes, or be used directly via: - $ conda env create -f conda/environment.yml + $ conda env create -f common/conda/environment.yml Pulling in dependencies may take a while depending on your internet connection. After the environment setup succeeded, you can activate it with: diff --git a/common/README.md b/common/README.md new file mode 100644 index 0000000000000000000000000000000000000000..e6828ed8d3e73a3d9fa765fff47ccf4427eeb3ea --- /dev/null +++ b/common/README.md @@ -0,0 +1,123 @@ +# `common/`: LALSuite common code and maintainer scripts + +This directory contains common code used by the constituent LALSuite +packages. It also contains miscellaneous scripts useful for maintenance. + +## `common/conda/`: LALSuite Conda packages + +This directory contains common code for Conda packages. + +## `common/debian/`: LALSuite Debian packages + +This directory contains common code for Debian packages. + +## `common/doxygen/`: LALSuite Doxygen documentation + +Online HTML documentation for the LALSuite C libraries and Pure-python extras +is generated using [Doxygen](http://www.doxygen.nl/). + +This directory contains the common files that are shared between the doxygen +builds for all of the LALSuite subpackages. + +The build is controlled by the automake file `gnuscripts/lalsuite_doxygen.am`, +customisations for each subpackage can be added in +`/doxygen/Makefile.am`. + +## `common/maintainer-scripts`: Maintainer scripts + +This directory contains miscellaneous scripts useful for maintenance: + +- `check_library_dependencies`: check for consistent library dependencies across + `.gitlab-ci.yml`, autotools, and the Conda, Debian, and RPM packages. This + script is run by the `lint:depends` GitLab CI job + +- `cleanup_mailmap_entries`: perform some cleanup operations on the Git `.mailmap` file: + - sync `.mailmap` with Git log entries; + - provide unique author/email mappings; + - prefer `ligo.org` email addresses. + +- `get_library_dependencies_from_c_headers`: determine library dependencies by + tracking C header usage between libraries. This might be useful during major + reorganisation where one wanted to confirm library dependencies. Will muck up + a local build since it stores preprocessed code in `.o` files. + +- `xlalify_function_calls`: attempt to convert old `LALStatus`-type LAL + functions to XLAL functions, as well as calls to those functions. Relies on + regular expression matching based on common coding patterns in old `LALStatus` + code. Call without arguments for usage. Use at your own risk!! + +## `common/swig`: LALSuite SWIG Bindings + +The LALSuite C libraries are wrapped using [SWIG](http://swig.org/) +to provide Octave and Python bindings for each library. + +The wrappings are built as follows: + +1. A boilerplate pre-processed interface file `swig.i_preproc.i` is + generated that `%include`s all of the package header (`.h`) files. + +2. An XML representation of the library is generated by running + `swig -xml swig.i_preproc.i`. + +3. The XML representation is passed to `generate_swig_iface.py` to generate + the actual SWIG interface file `swigi`. + + This script also handles generic object renaming (e.g. stripping `XLAL` + prefices from functions). See `swig_function_prefixes` in the + `/swig/Makefile.am` for each package for the list of prefixes that are + stripped, and `common/swig/generate_swig_iface.py` for the variable and constant + renames. + +4. The SWIG C library files for each high-level binding are generated by + running `swig -{octave,python} swig.i`. + + The following files modify the build for each subpackage: + + - `/swig/SWIGCommon.i` (LAL only) + - `/swig/SWIGAlpha.i` (always `%include`d first) + - `/swig/SWIGOmega.i` (always `%include`d last) + - `/swig/SWIGOctave.i` + - `/swig/SWIGPython.i` + +5. The C library for each binding is compiled. + +## `common/test`: Test utilities for LALSuite + +This directory contains generic testing utilities for LALSuite. + +### `test_python_imports.py` + +This script discovers all python modules in the `/python//` +tree and sets up a unit test to run `import `. + +This script must be symlinked to `/test/python/` and +referenced from the `Makefile.am` in that directory to run properly. + +It can be accompanied by `exclude-modules.txt` (in the same directory) that lists out +the _file paths_ of modules to exclude from the test relative to the `/python/` +directory, e.g. to exclude `lal.git_version` from the tests you would put + +``` +lal/git_version.py +``` + +into `exclude-modules.txt`. + +### `test_python_scripts.py` + +This script discovers all python scripts in the `/python` directory +and sets up a unit test to run `