Travis CI Administration Notes

Managing Travis Builds

Basic Facts

• Travis CI configuration is in file .travis.yml, and build scripts are in bin/build-*linux.sh. Only Linux builds are currently supported.
• MPICH, Libint, and MADNESS+TiledArray installation directories are cached. Build scripts only verify the presence of installed directories, and do not update them if their configuration (e.g. static vs. shared, or code version) has changed. Thus it is admin's responsibility to manually wipe out the cache on a per-branch basis. It is the easiest to do via the Travis-CI web interface (click on 'More Options' menu at the top right, select 'Caches', etc.).

Debugging

Remote debugging

This method has you log directly into the running Travis-CI container via ssh. However, it is fairly inconvenient because there is a short time limit for debugging and (unlikely, but possible) you may have to spend time compiling prerequisites manually (only if they are not in the job cache).

• Click the 'Debug job' button on the job page, e.g. see here
• The job will start booting up ... watch until the output stops. Execute the ssh command listed in the output. N.B. To ssh you may need to explicitly use an SSH key, i.e. ssh -i <key file> <address>. Ask Google to learn how to create an SSH key.
• Cut and paste the commands listed in .travis.yml in before_install section ... this will compile all prerequisites. These scripts do not exist remotely, so you will need to cut and paste the contents of these scripts.

There is a 30 minute limit, so you will probably want to use the local debugging method for more serious debugging.

Local debugging

This method requires Docker installed on your local machine. This also assumes that you start at the top of the MPQC source tree.

1. Create a Travis-CI 'Trusty' docker image: bin/docker-travis-build.sh
2. Run a container using the newly created image: docker run -it mpqc4-travis-debug bash -l
3. cd /home/travis/_build
4. Configure the job to use the appropriate compiler, compiler version, and debug/release build type:

• export BUILD_TYPE=B, where B is Debug or Release.
• If want to use GNU C++ compiler (gcc):
  • export GCC_VERSION=VVV where VVV should be the GCC version to be used. The currently valid values are 5, 6, 7, and 8.
  • export CXX=g++
• If want to use Clang C++ compiler (clang++):
  • export GCC_VERSION=7
  • export CLANG_VERSION=VVV where VVV should be the GCC version to be used. The currently valid values are 5.0, 6.0 and 7.
  • export CXX=clang++

5. Build prerequisites (MPICH, libint, TiledArray), MPQC, and run tests: ./build.sh

Notes

• According to Travis-CI docs you want to configure your Docker to run containers with 2 cores and 4 GB of RAM to best match the production environment.
• If you plan to use this container multiple times it might make sense to take a snapshot at this point to avoid having to recompile the prerequisites each and every time. Store it as a separate image, e.g. docker commit container_id mpqc4-travis-debug:clang-debug, where container_id can be found in the output of docker ps. Next time to start debugging you will need to pull updates to MPQC source (do cd /home/travis/build/ValeevGroup/mpqc4 && git pull), then execute step 2 with the new image name, execute step 3, and go directly to step 6.
• To install gdb execute apt-get update && apt-get install gdb. Also, it appears that to be able to attach gdb or any other debugger to a running process you must run the Docker container in privileged mode as docker run --privileged -it mpqc4-travis-debug:clang-debug bash -l.
• To debug parallel jobs you want to give -D to the mpqc executable. You will then also need to run the container so that it can connect to the XWindows server on it as explained here. N.B. I never managed to get the XWindows port magic, so what I do is start an ssh server in the container and log in from an xterm:
  • Connect sshd's port of the container (22) to an unprivileged port (say, 2222) of the host: docker run -p 127.0.0.1:2222:22 --privileged -it mpqc4-travis-debug:clang-debug bash -l
  • Generate host keys: ssh-keygen -A
  • Create a root password: passwd and follow prompts. No need to be fancy: security is not a concern here, but passwd will not accept an empty password. N.B. This is easier than setting up a pubkey login, so don't bother with that.
  • Edit /etc/ssh/sshd_config and allow root to log in by ensuring that PermitRootLogin and PasswordAuthentication are set to yes.
  • Start ssh server: /etc/init.d/ssh start
  • You should be able to log in from an xterm on the host side: ssh -X -p 2222 root@localhost
  • Now run MPQC with -D and MPQC will be able to launch xterm windows.