Using the checkin script

When to use the checkin script

You must use the checkin script if you are modifying source code, examples or tests. The checkin script isn't necessary if you're making documentation changes.

Preparing to run the checkin script

Step 1

Create the directory CHECKIN. This directory can be anywhere. If you create it in the root of your Trilinos source directory that contains the commits you want to check in, then you must add /CHECKIN to Trilinos/.gitignore.

Note (LBV): adding /CHECKIN to Trilinos/.git/info/exclude avoids modifying and pushing the Trilinos/.gitignore which can be useful for this type of local setup

Step 2

Create the file CHECKIN/COMMON.config, which will hold the minimal set of cmake options that are common to all builds, e.g., TPL locations, general cmake options, etc. The format is one cmake configure option per line. Do not use backslashes as line terminators!

At a minimum, COMMON.config should contain the following entries:

-D BUILD_SHARED_LIBS:BOOL=ON
-D Trilinos_ENABLE_EXPLICIT_INSTANTIATION:BOOL=ON
-D TPL_BLAS_LIBRARIES:PATH=/usr/local/lapack/rhel6/libblas.so
-D TPL_LAPACK_LIBRARIES:PATH=/usr/local/lapack/rhel6/liblapack.so
-D ParMETIS_LIBRARY_DIRS:PATH="${SEMS_PARMETIS_LIBRARY_PATH}"
-D ParMETIS_INCLUDE_DIRS:PATH="${SEMS_PARMETIS_INCLUDE_PATH}"
-D SuperLU_INCLUDE_DIRS:PATH="${SEMS_SUPERLU_INCLUDE_PATH}"
-D SuperLU_LIBRARY_DIRS:PATH="${SEMS_SUPERLU_LIBRARY_PATH}"
-D BoostLib_INCLUDE_DIRS:PATH="${SEMS_BOOST_INCLUDE_PATH}"
-D BoostLib_LIBRARY_DIRS:PATH="${SEMS_BOOST_LIBRARY_PATH}"
-D BOOST_INCLUDE_DIRS:PATH="${SEMS_BOOST_INCLUDE_PATH}"
-D BOOST_LIBRARY_DIRS:PATH="${SEMS_BOOST_LIBRARY_PATH}"
-D yaml-cpp_INCLUDE_DIRS:PATH="${SEMS_YAML_CPP_INCLUDE_PATH}"
-D yaml-cpp_LIBRARY_DIRS:PATH="${SEMS_YAML_CPP_LIBRARY_PATH}"

You will need to adapt the paths as necessary for the particular TPLS that you are using.

Step 3

Run the checkin script (you must prepend the path to the script):

checkin-test.py --ctest-timeout=600 --do-all -j 16 --push

The --do-all option causes a reconfigure/rebuild. If the builds and tests all pass, the --push option causes a git push to the Trilinos repo.

Note (LBV): even though you can modify the amount of timeout for the tests, it is the recommended policy to use the default --ctest-timeout=300, to avoid pushing a long test that could inadvertently block others that use the default timeout

Extras

To disable certain packages

checkin-test.py --ctest-timeout=600 --do-all -j 16 --push --disable-packages='Stokhos,TrilinosCouplings'

To run the checkin script but use previous results

checkin-test.py --enable-packages=Blah --default-builds=MPI_DEBUG --do-all   #builds, runs tests, some fail
checkin-test.py --enable-packages=Blah --default-builds=MPI_DEBUG --push --force-push    #uses results from prior run, pushes

To disable certain tests in checkin-script:

checkin-test.py --ctest-timeout=600 --st-extra-builds=MPI_SS_DEBUG,SERIAL_SS_RELEASE --do-all -j 16 --push --ctest-options="-E '(Belos_pseudo_ptfqmr_hb_1_MPI_4|Belos_pseudo_ptfqmr_hb_3_MPI_4)'"

How to setup separate development and checkin repositories

The goal is to be able to work on the development repository while the checkin script is running on a separate repository. The workflow described here transfer local commits of the development repository to the checkin repository. Repositories can either be set on the same machine or on two different machines. In the following, the development machine is called DEV, checkin machine is called CHECK. Your development repository is DEV:~/dev/Trilinos

kinit can be used to avoid repeatedly entering your password.

Setting up the environment on CHECK

To create the checkin repository:

git clone [email protected]:trilinos/Trilinos.git

Switch to the development branch:

git checkout develop

To create an alias referring to your development repository (optional):

git remote add dev DEV:~/dev/Trilinos

Notes:

• 'dev' is the alias name of DEV:~/dev/Trilinos
• git remote add adds a remote repository that you can either push to or pull from.
• git remote add can also be used on the development repository to create an alias to the checkin repository

Exclude the CHECKIN directory from git:

echo CHECKIN >> .git/info/exclude

Daily workflow

On DEV: update repository first to avoid merging problems

git pull --rebase

On CHECK:

• update repository first to avoid merging problems
• transfer your commit from your dev repository to the checkin script repository
• run the check-in script

git pull --rebase
git pull --rebase dev develop #or git pull --rebase DEV:~/dev/Trilinos develop
cd CHECKIN; ../checkin-test.py [your usual options]

Note: it's also possible to push from DEV to CHECK instead of pulling from CHECK.

External resources

https://github.com/trilinos/Trilinos/wiki/Policies-|-Safe-Checkin-Testing