path: root/README.md

Reproducible source for Akhlaghi et al. (2020, arXiv:2006.03018)
----------------------------------------------------------------

Copyright (C) 2018-2020 Mohammad Akhlaghi <mohammad@akhlaghi.org>\
See the end of the file for license conditions.

This is the reproducible project source for the paper titled "**Towards
Long-term and Archivable Reproducibility**", by Mohammad Akhlaghi, Raúl
Infante-Sainz, Boudewijn F. Roukema, David Valls-Gabaud, Roberto
Baena-Gallé, see [arXiv:2006.03018](https://arxiv.org/abs/2006.03018) or
[zenodo.3872247](https://doi.org/10.5281/zenodo.3872247).

To learn more about the purpose, principles and technicalities of this
reproducible paper, please see `README-hacking.md`. In the "Quick start"
section below we show a minimal set of commands to clone, and reproduce the
full project using Git. In the next section the commands are explained
more. The following section describes how to deal with a tarball of the
project's source (not using Git). In the last section building the project
within a Docker container is described.





### Quick start (using Git, with internet access)

Run these commands to clone this project's history, enter it, configure it
(let it build and install its own software) and "make it (let it do
reproduce its analysis). If you already have the project on your system,
you can ignore the first step (cloning). In the core Maneage branch, all
operations will be done in the build-directory that you specify at
configure time, no root permissions are required and no other part of your
filesystem is affected.

```shell
$ git clone https://gitlab.com/makhlaghi/maneage-paper
$ cd maneage-paper
$ ./project configure
$ ./project make
```





### Building the project

This project was designed to have as few dependencies as possible without
requiring root/administrator permissions.

1. Necessary dependencies:

   1.1: Minimal software building tools like a C compiler and other very
        basic POSIX tools found on any Unix-like operating system
        (GNU/Linux, BSD, Mac OS, and others). All necessary dependencies
        will be built from source (for use only within this project) by the
        `./project configure` script (next step). Note that **Git is not
        mandatory**: if you don't have Git to run the first command above,
        go to the URL given in the command on your browser, and download
        the project's source (there is a button to download a compressed
        tarball of the project). You can also get project's source as a
        tarball from arXiv or Zenodo.

   1.2: (OPTIONAL) Tarball of dependencies. If they are already present (in
        a directory given at configuration time), they will be
        used. Otherwise, a downloader (`wget` or `curl`) will be necessary
        to download any necessary tarball. The necessary tarballs are also
        collected in the archived project on Zenodo (link below). Just
        unpack that tarball, and when `./project configure` asks for the
        "software tarball directory", give the address of the unpacked
        directory: https://doi.org/10.5281/zenodo.3911395

2. Configure the environment (top-level directories in particular) and
   build all the necessary software for use in the next step. It is
   recommended to set directories outside the current directory. Please
   read the description of each necessary input clearly and set the best
   value. Note that the configure script also downloads, builds and locally
   installs (only for this project, no root privileges necessary) many
   programs (project dependencies). So it may take a while to complete.

     ```shell
     $ ./project configure
     ```

3. Run the following command to reproduce all the analysis and build the
   final `paper.pdf` on `8` threads. If your CPU has a different number of
   threads, change the number (you can see the number of threads available
   to your operating system by running `./.local/bin/nproc`)

     ```shell
     $ ./project make -j8
     ```










### Building project tarball (without Git)

If the paper is also published on arXiv, it is highly likely that the
authors also uploaded/published the full project there along with the LaTeX
sources. If you have downloaded (or plan to download) this source from
arXiv, some minor extra steps are necessary as listed below. This is
because this tarball is mainly tailored to automatic creation of the final
PDF without actually using the './project' command! You can directly run
'latex' on this directory and the paper will be built with no analysis (all
necessary built products are already included).



#### Only building PDF using tarball (no analysis)

1. If you got the tarball from arXiv and the arXiv code for the paper
   is 1234.56789, then the downloaded source will be called
   `1234.56789` (no special identification suffix). However, it is
   actually a `.tar.gz` file. So take these steps to unpack it to see
   its contents.

     ```shell
     $ arxiv=1234.56789
     $ mv $arxiv $arxiv.tar.gz
     $ mkdir $arxiv
     $ cd $arxiv
     $ tar xf ../$arxiv.tar.gz
     ```

2. No matter how you got the tarball, if you just want to build the PDF
   paper from the tarball, simply run the command below. Note that this
   won't actually install any software or do any analysis, it will just use
   your host operating system to build the PDF and assums you already have
   all the necessary LaTeX packages.

   ```shell
   $ make              # Build PDF in tarball without doing analysis
   ```

3. If you want to re-build the figures from scratch, you need to make the
   following corrections to the paper's main LaTeX source (`paper.tex`):
   uncomment (remove the starting `%`) of the line containing
   `\newcommand{\makepdf}{}`. See the comments above it for more
   information.



#### Building full project from tarball (custom software and analysis)

Since the tarball is mainly geared to only building only the final PDF, a
few small tweaks are necessary to build the full project from scratch
(download necessary software and data, build them and run the analysis and
finally create the final paper).

1. If you got the tarball from arXiv, before following the standard
   procedure of projects described at the top of the file above (using the
   './project' script), its necessary to set its executable flag. arXiv
   removes the executable flag from the files (for its own security).

     ```shell
     $ chmod +x project
     ```

2. Make the following change in two of the LaTeX files so LaTeX attempts to
   build the figures from scratch (to make the tarball, it was configured
   to avoid building the figures, just using the ones that came with the
   tarball).

   - `paper.tex`: uncomment (remove the starting `%`) of the line
     containing `\newcommand{\makepdf}{}`. See the comments above it for
     more information.

   - `tex/src/preamble-pgfplots.tex`: set the `tikzsetexternalprefix`
     variable value to `tikz/`, so it looks like this:
     `\tikzsetexternalprefix{tikz/}`.

3. Remove extra files. In order to make sure arXiv can build the paper
   (resolve conflicts due to different versions of LaTeX packages), it is
   sometimes necessary to copy raw LaTeX package files in the tarball
   uploaded to arXiv. Later, we will implement a feature to automatically
   delete these extra files, but for now, the project's top directory
   should only have the following contents (where `reproduce` and `tex` are
   directories). You can safely remove any other file/directory.

     ```shell
     $ ls
     COPYING  paper.tex  project  README-hacking.md  README.md  reproduce  tex
     ```





### Building in Docker containers

Docker containers are a common way to build projects in an almost
independent filesystem and operating system. They also allow using a
minimal GNU/Linux operating system for each project within proprietary
operating systems like macOS or Windows. The steps below describe the
necessary components of a `Dockerfile` to build this project in a Docker
image with some explanations on each. You can just copy the code parts of
each item into a plain-text file called `Dockerfile` and apply the
necessary corrections in the copying phase (step 4), then run this command
to build the Docker image (note that Docker only runs as root!):

```shell
docker build ./
```

**NOTE: Internet necessary for TeXLive:** With the commands below in your
`Dockerfile`, you can disable the image's internet just after downloading
the necessary packages (step 2). However, until [task
15267](https://savannah.nongnu.org/task/?15267) is complete, the project
will need internet access to download the necessary TeXLive packages (in
the `./project configure` phase) to build the final PDF. Without TeXLive,
the analysis will be exactly reproduced, LaTeX macros will be created and
everything will be verified successfully (all in the build directory),
however, no PDF will be built to visualize/combine them in one file.

 1. **Choose the base operating system:** The first step is to select the
    operating system that will be used in the docker image. Note that your
    choice of operating system also determines the commands of the next
    step.

    ```
    FROM debian:stable-slim
    ```

 2. **Necessary packages:** By default the "slim" versions of the operating
    systems don't contain a compiler, so you need to use their package
    managers to get them. Also, currently (until [task
    15481](https://savannah.nongnu.org/task/?15481) is complete), Maneage
    doesn't yet build Xorg libraries that are necessary in tools like
    Ghostscript to build PDFs (not related to the project's analysis).

    ```
    # C and C++ compiler.
    RUN apt-get update && apt-get install -y gcc g++

    # Necessary Xorg libraries (which aren't yet installed, see task 15481).
    RUN apt-get install -y libxext-dev libxt-dev libsm-dev libice-dev

    # Uncomment this for a text editor (to modify files after image is built).
    #RUN apt-get install -y nano
    ```

 3. **Define a user:** Some packages will complain if you try to install
    them as the default (root) container user. Generally, its also good
    practice to avoid being the root user. After building the Docker image,
    you can always run it as root with this command: `docker run -u 0 -it
    XXXXXXX` (where `XXXXXXX` is the image identifier).

    ```
    RUN useradd -ms /bin/sh maneager
    USER maneager
    WORKDIR /home/maneager
    ```

 4. **Copy project files into the container:** these commands make the
    following assumptions:

    * The project's source is in the `maneaged-project/` subdirectory of
      the directory that you will run `docker build` in. The source can
      either from Git or from a tarball, both described above (note that
      arXiv's tarball needs to be corrected as mentioned above).

    * (OPTIONAL, with internet) The project's software tarball (packaged in
      `software-XXXX.tar.gz` and downloadable from the Zenodo link above,
      just correct the `XXXX` part manually) is the same directory that you
      will run `docker build` in. This is not mandatory: if you have
      internet, the project will download its necessary software
      automatically.

    * (OPTIONAL, with internet) The project's input data. The `INPUT-FILES`
      depends on the project, please look into the project's
      `reproduce/analysis/config/INPUTS.conf` for the URLs and file
      names. This is not mandatory: if you have internet, the project will
      download its necessary software automatically.

    ```
    RUN mkdir build
    COPY --chown=maneager:maneager ./maneaged-project /home/maneager/source

    # Optional (for software and data, if internet is available)
    RUN mkdir data
    COPY --chown=maneager:maneager ./INPUT-FILES /home/maneager/data
    COPY --chown=maneager:maneager ./software-XXXX.tar.gz /home/maneager/
    RUN tar xf software-XXXX.tar.gz && mv software-XXXX software && rm software-XXXX.tar.gz
    ```

 5. **Configure the project:** The Docker image will configure the project
    (let the project build all its necessary software).

    ```
    RUN cd /home/maneager/source \
           && ./project configure --build-dir=/home/maneager/build \
                                  --software-dir=/home/maneager/software \
                                  --input-dir=/home/maneager/data
    ```

 6. **Do the project's analysis:** You are now ready to add the instruction
    to automatically reproduce the project's analysis.

    ```
    RUN cd /home/maneager/source && ./project make
    ```





### Copyright information

This file and `.file-metadata` (a binary file, used by Metastore to store
file dates when doing Git checkouts) are part of the reproducible project
mentioned above and share the same copyright notice (at the start of this
file) and license notice (below).

This project 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 project 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 project.  If not, see <https://www.gnu.org/licenses/>.