1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
Reproducible source for paper introducing Maneage (MANaging data linEAGE)
-------------------------------------------------------------------------
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é.
To reproduce the results and final paper, the only dependency is a minimal
Unix-based building environment including a 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, please see the respective section below.
*IMPORTANT NOTE*: If you want to build using a distributed tarball that
isn't under Git's version control, see the points below under building
project tarball, a few minor modifications need to be made before starting
the project configuration and build.
```shell
$ git clone https://gitlab.com/makhlaghi/maneage-paper
$ cd maneage-paper
$ ./project configure
$ ./project make
```
To learn more about the purpose, principles and technicalities of this
reproducible paper, please see `README-hacking.md`. For a general
introduction to reproducible science as implemented in this project
(through Maneage), please see Maneage project's webpage at
https://maneage.org.
### 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 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.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 that has all the tarballs.
https://doi.org/10.5281/zenodo.3872248
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 (possibly from arXiv)
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
```
### 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/>.
|
