docs

Notes on manual pages

The manual pages are generated using rst2man(1). To recreate them, run make man in the toplevel folder. If you want to edit the documentation for upstream changes, make sure to edit the *.rst files and not the shipped nroff output files.

Notes on debugging Travis failures

This is based on https://docs.travis-ci.com/user/common-build-problems/

Travis works by getting a webhook notification when a commit is pushed to github. It then starts up a docker container, does a shallow git pull of the repo and the branch, and runs the instructions in the .travis.yml file.

If you run docker locally you can connect into the environment and poke around. So the steps are.

Install docker

sudo -E swupd bundle-add containers-basic

Get docker working

Get docker run hello-world working. TODO: fill in some details - assistance welcome.

Start the travis image

At the time of writing, the current image for the default target is travisci/ci-garnet:packer-1512502276-986baf0

Start a detached image running /sbin/init (i.e. a system that is booted normally). You probably will want this to be privileged, so you can use tools like gdb or strace.

docker run --name travis-debug -dit --privileged travisci/ci-garnet:packer-1512502276-986baf0 /sbin/init

This should return pretty quickly. Now connect to it and run a shell.

docker exec -it travis-debug bash -i

Become the travis user, set up any environment variables needed. These could be added into ~/.bashrc if desired.

su - travis export http_proxy=... https_proxy=

Pull the code from github

git clone --depth=50 --branch=master https://github.com/clearlinux/swupd-client.git

Edit the .git/config file to add in the non-standard names that github uses, so it looks like this

[remote "origin"]
    url = https://github.com/clearlinux/swupd-client.git
    fetch = +refs/heads/master:refs/remotes/origin/master
    fetch = +refs/pull/*/head:refs/remotes/origin/pr/*

then you can get it by name, e.g.

git checkout origin/pr/502

Update the environment according to the commands in the .travis.yml file, e.g. follow the instructions in the install section of the file. You can use this crude function to get a section out of a yaml file.

S(){ sed '1,/^'"${1?Missing section name}"':/d;/^[^ t]*:/Q;s/^[ t]*-//' "${2:-.travis.yml}" ; }

which you can then pipe to a shell after you have checked it, i.e.

S install
        wget https://github.com/libcheck/check/releases/download/0.11.0/check-0.11.0.tar.gz
        tar -xvf check-0.11.0.tar.gz
        pushd check-0.11.0 && ./configure --prefix=/usr && make -j48 && sudo make install && popd
        wget https://github.com/clearlinux/bsdiff/releases/download/v1.0.2/bsdiff-1.0.2.tar.xz
        tar -xvf bsdiff-1.0.2.tar.xz
        pushd bsdiff-1.0.2 && ./configure --prefix=/usr --disable-tests && make -j48 && sudo make install && popd
        wget https://curl.haxx.se/download/curl-7.51.0.tar.gz
        tar -xvf curl-7.51.0.tar.gz
        pushd curl-7.51.0 && ./configure --prefix=/usr && make -j48 && sudo make install && popd
        wget https://download.clearlinux.org/releases/13010/clear/Swupd_Root.pem
        sudo install -D -m0644 Swupd_Root.pem /usr/share/clear/update-ca/Swupd_Root.pem
        wget https://github.com/libarchive/libarchive/archive/v3.3.1.tar.gz
        tar -xvf v3.3.1.tar.gz
        pushd libarchive-3.3.1 && autoreconf -fi && ./configure --prefix=/usr && make && sudo make install && popd
        sudo apt-get install python3-docutils
        sudo apt-get install realpath
        sudo ln -s /usr/share/docutils/scripts/python3/rst2man /usr/bin/rst2man.py

       # Ubuntu's default umask is 0002, but this break's swupd hash calculations.

 S install | bash -x

Once this is done, you can actually run the job, this is the script section of the .travis.yml file

S script
   sudo find test/functional -exec chmod g-w {} \;
   autoreconf --verbose --warnings=none --install --force &&
   ./configure &&
   make -j48 &&
   sudo sh -c 'umask 0022 && make -j48 check' &&
   sudo sh -c 'umask 0022 && make install'