diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 145 |
1 files changed, 76 insertions, 69 deletions
@@ -1,35 +1,44 @@ -Reproducible source for XXXXXXXXXXXXXXXXX -------------------------------------------------------------------------- +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 "**XXX XXXXX -XXXXXX**", by XXXXX XXXXXX, YYYYYY YYYYY and ZZZZZZ ZZZZZ that is published -in XXXXX XXXXX. - -To reproduce the results and final paper, the only dependency is a minimal -Unix-based building environment including a C and C++ compiler (already -available on your system if you have ever built and installed a software -from source) and a downloader (Wget or cURL). Note that **Git is not -mandatory**: if you don't have Git to run the first command below, 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). If you have received this source from arXiv or Zenodo (without -any `.git` directory inside), please see the "Building project tarball" -section below. +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 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX -$ cd XXXXXXXXXXXXXXXXXX +$ git clone https://gitlab.com/makhlaghi/maneage-paper +$ cd maneage-paper $ ./project configure $ ./project make ``` -This paper is made reproducible using Maneage (MANaging data linEAGE). To -learn more about its purpose, principles and technicalities, please see -`README-hacking.md`, or the Maneage webpage at https://maneage.org. - @@ -41,25 +50,25 @@ requiring root/administrator permissions. 1. Necessary dependencies: - 1.1: Minimal software building tools like C compiler, Make, and other - 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). + 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 - [https://doi.org/10.5281/zenodo.XXXXXXX](XXXXXXX). Just unpack that - tarball and you should see all the tarballs of this project's - software. When `./project configure` asks for the "software tarball - directory", give the address of the unpacked directory that has all - the tarballs. [[TO AUTHORS: UPLOAD THE SOFTWARE TARBALLS WITH YOUR - DATA AND PROJECT SOURCE TO ZENODO OR OTHER SIMILAR SERVICES. THEN - ADD THE DOI/LINK HERE. DON'T FORGET THAT THE SOFTWARE ARE A - CRITICAL PART OF YOUR WORK'S REPRODUCIBILITY.]] + 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 @@ -91,30 +100,26 @@ requiring root/administrator permissions. -### Building project tarball (possibly from arXiv) +### 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 using Maneage (only calling LaTeX, not 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 in the -tarball). One important feature of the tarball is that it has an extra -`Makefile` to allow easy building of the PDF paper without worring about -the exact LaTeX and bibliography software commands. +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 - suffix). However, it is actually a `.tar.gz` file. So take these steps - to unpack it to see its contents. +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 @@ -125,11 +130,10 @@ the exact LaTeX and bibliography software commands. ``` 2. No matter how you got the tarball, if you just want to build the PDF - paper, 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 (assuming you already have a LaTeX installation and all - the necessary LaTeX packages) to build the PDF using the already-present - plots data. + 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 assumes you already have + all the necessary LaTeX packages. ```shell $ make # Build PDF in tarball without doing analysis @@ -137,35 +141,36 @@ the exact LaTeX and bibliography software commands. 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 `%`) the line containing - `\newcommand{\makepdf}{}`, see the comments above it for more. + 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) -As described above, the tarball is mainly geared to only building 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). +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 because - arXiv removes the executable flag from the files (for its own security). + './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 changes 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). +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. + 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: @@ -181,7 +186,7 @@ analysis and finally create the final paper). ```shell $ ls - COPYING paper.tex project README-hacking.md README.md reproduce/ tex/ + COPYING paper.tex project README-hacking.md README.md reproduce tex ``` @@ -430,6 +435,8 @@ docker images -a -q | xargs docker rmi -f + + ### Copyright information This file and `.file-metadata` (a binary file, used by Metastore to store |