IMPORTANT: Apptainer and Docker containers, minor restructuringHEADmaneage

Summary: it is necessary to re-configure your project (just running
'./project configure -e', not deleting 'build/software' to re-build
software) after this commit, see "Affected files" item below).

Until now, we only had a relatively long set of manual instructions for
building Maneage within Docker in the top-level README. This was hard to
automate, focing Maneage users to write custom commands based on the
instructions and maintain those scripts outside of Maneage. As a result,
experience could not be shared between projects (or at most in the README
file!).

With this commit, a new 'reproduce/software/containers' directory has been
created within Maneage that contains two scripts (with a unified interface)
greatly simplifying the building of the project's software environment
within a container (one script for Apptainer and one for Docker). Two
READMEs have been added for each container to help in their first time
usage. Also, the old checklist within the main README has been replaced
with a short introduction on containers and points the interested readers
to the custom README of each container technology.

Since we wanted the containers to be read-only after build, we needed to
fully decouple the 'build/software' and 'build/analysis', such that
'./project configure' only writes to the former and './project make' only
writes the latter. The file and directories mentioned in the affected files
are cases that both project phases was writing to the 'build/software' and
'build/analysis' directories.

Affected files: 'preparation-done.mk' and 'lockdir' which were previously
in the 'build/software' directory are now made during the 'make' phase and
the 'configure' phase no longer builds the 'build/analysis' or anything
within it. Also, the software version LaTeX macros (which were previously
written during the 'configure' phase in the 'analysis' directory) are now
written in the software directory and copied into the analysis for usage in
LaTeX while building the paper.

Other minor additions in this commit:

  - The './project' script has a new '--timing' option to write the
    starting and ending times of the project in a file. It also builds the
    high-level analysis directories when './project make' is called (but
    before calling 'top-make.mk'.

  - The 'tar' calls in the custom build commands of the software building
    Makefiles now have the '--no-same-owner --no-same-permissions' options
    like the 'tar' call within the 'uncompress' function of
    'build-rules.mk'.

This commit was originally written by Giacomo Lorenzetti only for Apptainer
on the registered commit date. It was later re-implemented from scratch by
Mohammad Akhlaghi to have a unified interface for both Apptainer and Docker
and merged into Maneage on 2025-04-23.

1 files changed, 69 insertions, 0 deletions

diff --git a/reproduce/software/containers/README-apptainer.md b/reproduce/software/containers/README-apptainer.md
new file mode 100644
index 0000000..9608dc8
--- /dev/null
+++ b/reproduce/software/containers/README-apptainer.md
@@ -0,0 +1,69 @@
+# Maneage'd projects in Apptainer
+
+Copyright (C) 2025-2025 Mohammad Akhlaghi <mohammad@akhlaghi.org>\
+Copyright (C) 2025-2025 Giacomo Lorenzetti <glorenzetti@cefca.es>\
+See the end of the file for license conditions.
+
+For an introduction on containers, see the "Building in containers" section
+of the `README.md` file within the top-level directory of this
+project. Here, we focus on Apptainer with a simple checklist on how to use
+the `apptainer-run.sh` script that we have already prepared in this
+directory for easy usage in a Maneage'd project.
+
+
+
+
+
+## Building your Maneage'd project in Apptainer
+
+Through the steps below, you will create an Apptainer image that will only
+contain the software environment and keep the project source and built
+analysis files (data and PDF) on your host operating system. This enables
+you to keep the size of the image to a minimum (only containing the built
+software environment) to easily move it from one computer to another.
+
+ 1. Using your favorite text editor, create a `apptainer-local.sh` in your
+    project's top directory that contains the usage command shown at the
+    top of the 'apptainer.sh' script and take the following steps:
+    * Set the respective directories based on your own preferences.
+    * The `--software-dir` is optional (if you don't have the source
+      tarballs, Maneage will download them automatically. But that requires
+      internet (which may not always be available). If you regularly build
+      Maneage'd projects, you can clone the repository containing all the
+      tarballs at https://gitlab.cefca.es/maneage/tarballs-software
+    * Add an extra `--build-only` for the first run so it doesn't go onto
+      doing the analysis and just builds the image. After it has completed,
+      remove the `--build-only` and it will only run the analysis of your
+      project.
+
+ 2. Once step one finishes, the build directory will contain two
+    Singularity Image Format (SIF) files listed below. You can move them to
+    any other (more permanent) positions in your filesystem or to other
+    computers as needed.
+    * `maneage-base.sif`: image containing the base operating system that
+      was used to build your project. You can safely delete this unless you
+      need to keep it for future builds without internet (you can give it
+      to the `--base-name` option of this script). If you want a different
+      name for this, put the same option in your
+    * `maneaged.sif`: image with the full software environment of your
+      project. This file is necessary for future runs of your project
+      within the container.
+
+
+
+
+
+## Copyright information
+
+This file is free software: you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free
+Software Foundation, either version 3 of the License, or (at your option)
+any later version.
+
+This file is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+more details.
+
+You should have received a copy of the GNU General Public License along
+with this file.  If not, see <https://www.gnu.org/licenses/>.