diff options
| -rw-r--r-- | README | 55 | ||||
| -rw-r--r-- | README.md | 44 | ||||
| -rwxr-xr-x | configure | 2 | ||||
| -rw-r--r-- | reproduce/src/make/dependencies.mk | 1 |
4 files changed, 69 insertions, 33 deletions
@@ -1,23 +1,45 @@ -Reproduction pipeline for XXXXXXX +Reproduction pipeline for paper XXXXXXX +======================================= -For a general introduction to reproducible science as implemented in this -pipeline, please see the link below: +This is the reproduction pipeline for the paper titled "**XXXXXX**", +XXXXXXXX et al. YYYY (**IN PREPARATION**). By _reproduction pipeline_ it is +meant that the full instructions on build the necessary software packages +used in the analysis, and using them is provided in a human *and* computer +readable format, such that the simple commands below will *exactly* +reproduce what we have published (you just need Git, Wget, and minimal +Unix-based environment). + +```shell +$ git clone https://gitlab.com/makhlaghi/muse-ultra-diffuse-emitters.git +$ ./configure +$ ./.local/bin/make -j8 +``` - http://akhlaghi.org/reproducible-science.html +For a general introduction to reproducible science as implemented in this +pipeline, please see the [principles of reproducible +science](http://akhlaghi.org/reproducible-science.html), and a +[reproducible paper +template](https://gitlab.com/makhlaghi/reproducible-paper) that is based on +it. Running the pipeline -==================== +-------------------- + +This pipeline was designed to have as few dependencies as possible. 1. Necessary dependencies: - 1.1: Basic software building tools like C compiler, Make, and other + 1.1: Minimal software building tools like C compiler, Make, and other tools found on most Unix-like systems (GNU/Linux, BSD, Mac OS, and others). All necessary dependencies will be built from source by the `./configure' script (next step). - 1.2: Tarball of dependencies. If they are already present (in a + 1.2: Git to be able to manage the full version controlled history of + this project, including an initial "clone" to download it. + + 1.3: Tarball of dependencies. If they are already present (in a directory given at configuration time), they will be used. Otherwise, *GNU Wget* will be used to download any necessary tarball. The necessary tarballs are also collected in the link @@ -27,15 +49,22 @@ Running the pipeline 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 modify the directories. Please read the description of - each necessary input clearly and set the best value. Note that the - configure scripts also downloads, builds and locally installs many - programs (pipeline dependencies). So it may take a while to complete. + 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 many programs (pipeline dependencies). So it may take a while + to complete. + ```shell $ ./configure + ``` 3. Run the following command (local build of Make) 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. + 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 $ ./.local/bin/make -j8 + ``` @@ -451,6 +451,8 @@ advanced in later stages of your work. $ git config remote.origin.tagopt --no-tags # No tags in future fetch/pull from this pipeline. $ git remote rename origin pipeline-origin # Rename the pipeline's remote. $ git checkout -b master # Create, enter master branch. + $ mv README.md README-pipeline.md # No longer main README. + $ mv README README.md # Project's main README. ``` - **Test the pipeline**: Before making any changes, it is important to @@ -465,18 +467,18 @@ advanced in later stages of your work. pipeline outputs with `make clean` as shown below. ```shell - $ ./configure # Set top directories and build dependencies. - $ make # Run the pipeline. + $ ./configure # Set top directories and build dependencies. + $ ./.local/bin/make # Run the pipeline. # Open 'paper.pdf' and see if everything is ok. - $ make clean # Delete high-level outputs. + $ ./.local/bin/make clean # Delete high-level outputs. ``` - **Copyright**, **name** and **date**: Go over the existing scripting files and add your name and email to the copyright notice. You can find the files by searching for the placeholder email `your@email.address` (which you should change) with the command below - (you can ignore this file, `README.md`, and any in the `tex/` + (you can ignore this file, `README-pipeline.md`, and any in the `tex/` directory). Don't forget to add your name after the copyright year also. When making new files, always remember to add a similar copyright statement at the top of the file and also ask your @@ -500,9 +502,10 @@ advanced in later stages of your work. reason for this is to demonstrate how critically important it is to version your scientific tools. If you don't need Gnuastro for your research, you can simply remove the parts enclosed in marked parts in - the relevant files. The marks are comments, which you can find by - searching for "Gnuastro". If you will be using Gnuastro, you can - remove the commented marks and keep the + the relevant files of the list below. The marks are comments, which + you can find by searching for "Gnuastro". If you will be using + Gnuastro, then remove the commented marks and keep the code within + them. - Delete marked part(s) in `configure`. - Delete `astnoisechisel` from the value of `top-level-programs` in `reproduce/src/make/dependencies.mk`. You can keep the rule to build `astnoisechisel`, since its not in the `top-level-programs` list, it (and all the dependencies that are only needed by Gnuastro) will be ignored. @@ -515,12 +518,14 @@ advanced in later stages of your work. commented thoroughly and reading over the comments should guide you on what to add/remove and where. - - **`README`**: Go through this top-level instruction file and make it fit - to your pipeline: update the text and etc. Don't forget that your - colleagues or anyone else, will first be drawn to read this file, so - make it as easy as possible for them to understand your - work. Therefore, also check and update `README` one last time when you - are ready to publish your work (and its reproduction pipeline). + - **`README.md`**: (initially called `README`) Go through this top-level + instruction file and make it fit to your pipeline: update the text to + give a short description of your research project/paper and etc. Don't + forget that your colleagues or anyone else, will first be drawn to + read this file, so make it as easy as possible for them to understand + your work. Therefore, also check and update `README.md` one last time + when you are ready to publish your work (and its reproduction + pipeline). - **Input dataset (can be done later)**: The user manages the top-level directory of the input data through the variables set in @@ -585,12 +590,13 @@ advanced in later stages of your work. commit to be sure it works as expected). ```shell - $ ./.local/bin/make clean # Delete outputs ('make distclean' for everything) - $ ./.local/bin/make # Build the pipeline to ensure everything is fine. - $ git add -u # Stage all the changes. - $ git status # Make sure everything is fine. - $ git commit # Your first commit, add a nice description. - $ git tag -a v0 # Tag this as the zero-th version of your pipeline. + $ ./.local/bin/make clean # Delete outputs ('make distclean' for everything) + $ ./.local/bin/make # Build the pipeline to ensure everything is fine. + $ git add -u # Stage all the changes. + $ git add README-pipeline.md # Keep this pipeline description. + $ git status # Make sure everything is fine. + $ git commit # Your first commit, add a nice description. + $ git tag -a v0 # Tag this as the zero-th version of your pipeline. ``` - **Setup the remote**: You can use any [hosting @@ -47,7 +47,9 @@ pdir=$cdir/pipeline pconf=$pdir/LOCAL.mk ptconf=$pdir/LOCAL_tmp.mk poconf=$pdir/LOCAL_old.mk +# --------- Delete for no Gnuastro --------- glconf=$cdir/gnuastro/gnuastro-local.conf +# ------------------------------------------ diff --git a/reproduce/src/make/dependencies.mk b/reproduce/src/make/dependencies.mk index 455a3b8..9ee2dcf 100644 --- a/reproduce/src/make/dependencies.mk +++ b/reproduce/src/make/dependencies.mk @@ -333,7 +333,6 @@ $(ibdir)/texlive-ready: reproduce/config/pipeline/dependency-texlive.mk \ # `tlmgr' just hangs waiting. echo; echo; echo "Downloading necessary TeX packages..."; echo; tlmgr install $(texlive-packages) - echo "returned: $$?"; echo; echo; # Make a symbolic link of all the TeX Live executables in the bin # directory so we don't have to modify `PATH'. |