Skip to content

Development

Jump to bottom
kaskr edited this page Jun 4, 2017 · 20 revisions

Guidelines

Developers without write access to the adcomp repository can contribute with code or documentation by forking the project and sending a pull request once the code has been changed.

Recommended workflow (fork and pull request)

  • Let your own master branch be an exact copy of the official master branch:

    git remote add official https://github.com/kaskr/adcomp.git

    Synchronize frequently:

    git checkout master
git pull official master

  • Never commit directly to your master. Work on a local branch and send pull requests only for the local branch:

    git checkout -b local_branch

    Do work, commit and push to you github account:

    git push origin local_branch

    Send pull request for 'local_branch'.

  • Once your pull request is accepted, synchronize the master branch:

    git checkout master
git pull official master

    And delete you local branch

    git branch -d local_branch

    Remember to delete it on github:

    git push origin --delete local_branch

For developers with write access to the adcomp repository:

  • The master branch should be stable and never get into a broken state. Therefore: Never push changes directly to the master branch. Development must be performed on a separate branch (named by e.g. developers name or the topic of change) which is pushed to the adcomp repository.
  • When code is ready, send request to review and merge into the master branch.
  • The following tests must be performed before changes can be merged (to ensure nothing is broken on any platforms):
    • cd tmb_examples;make clean;make must pass.
    • The file REPORT.md must be inspected for inaccuracies and performance regressions.
    • runExample(all=TRUE) must pass.
    • Above should be tested with both gcc and clang on linux.
    • Tests should also be run on Windows and OSX.

Conventions

  • Text files should have Unix line endings. Check with file command from command line that output looks like e.g. sdv_multi.cpp: ASCII C program text without CR+LF.
  • Text files should not be executable.

Code formatting

Automated code formatting is recommended for new files

  • For internal C++ use

    clang-format-3.6 -i -style="{BasedOnStyle: Google, Standard: Cpp03}" file.cpp

  • For C++ model templates use

    clang-format-3.6 -i -style="{BasedOnStyle: Google, Standard: Cpp03, BreakBeforeBraces: Linux}" file.cpp

  • For R code use

    library(formatR)
tidy_source("file.R", arrow=TRUE)

Distributing code

Probably the easiest way to distribute TMB code is to use R's package functionality. You can get a test package working following these steps (with mypkg replaced by the name of your package):

  • package.skeleton("mypkg")

  • Copy model.cpp to mypkg/src

  • Add Depends: TMB LinkingTo: TMB, RcppEigen to the file mypkg/DESCRIPTION to ensure that TMB is loaded when mypkg is loaded, and that the TMB source code is found when compiling mypkg.

  • Add useDynLib(mypkg) to the file mypkg/NAMESPACE to ensure that the compiled code is loaded when you load the package.

  • Pass DLL="mypkg" to all MakeADFun calls.

  • Edit model.cpp to avoid CRAN notes:

    #define TMB_LIB_INIT R_init_mypkg
#include <TMB.hpp>

  • To avoid notes such as Found ‘_ZSt4cout’, possibly from ‘std::cout’ (C++) use the CRAN version of TMB when checking the package.

  • To avoid the warning Found ‘_abort’, possibly from ‘abort’ make sure the preprocessor flag -DTMB_SAFEBOUNDS does not appear during compilation (if you use your own Makefile pass safebounds=FALSE to compile).

Other notes:

Locating regressions and bugs

Suppose you update TMB and suddenly your model runs slow or has other issues. To find the commit that caused the problem, we can apply 'git bisect'.

  1. Clone a fresh adcomp folder and cd adcomp.

  2. Copy a selfcontained test example e.g. 'mymodel.R' and 'mymodel.cpp' to this folder.

  3. Make R-script 'bisect.R' containing:

    ## Re-install TMB and re-compile model:
system("make install")
library(TMB)
system("rm -f *.o *.so")
compile("mymodel.cpp")
## Run model under restricted permissions
status <- system("ulimit -t 20; R --vanilla < mymodel.R")
if(status != 0) stop("Fail")

    Here 'ulimit -t 20' interrupts the model run if it takes more than 20 sec. Alternatively 'ulimit -v 100000' would trigger interruption if the model uses more than 100Mb.

  4. Make an executable shell script 'bisect.sh' containing:

    #/bin/bash
R --vanilla < bisect.R

  5. Verify that the script fails now and that it worked e.g. 40 commits ago:

    git checkout master
./bisect.sh
git checkout HEAD~40
./bisect.sh

  6. Now we can start bisecting:

    git checkout master
git bisect start
git bisect bad HEAD
git bisect good HEAD~40
git bisect run ./bisect.sh

    The first bad commit will be displayed.

Clone this wiki locally