Building and Testing the TEI Guidelines and Stylesheets Hugh Cayless TEI Technical Council 2016 Born digital document. How to build and test the Guidelines and Stylesheets Getting set up to run the various building and testing targets in the Guidelines and Stylesheets is relatively easy in Debian-based Linuxes like Ubuntu. But it is quite tricky on other systems, like Mac OS X or Windows. The TEI Jenkins server will run a variety of builds when you push changes to the TEI or Stylesheets repos, but you may find you prefer to run the tests locally, as they will likely be faster and will save you the trouble of waiting for Jenkins to email you when it finds a problem. Moreover, if you’re doing work in a branch, Jenkins won’t help you at all, and it can be very useful to “check your work” as you go to avoid lots of bug-fixing when your merge back into dev. The first step in setting up your development and testing environment is to get copies of the TEI and Stylesheets repositories. These can be obtained from and respectively. All of the following instructions assume you are at least somewhat comfortable working in a command line environment. If you aren’t, this would be a good time to learn. A rather Mac-biased tutorial may be found at “Learn Enough Command Line to Be Dangerous”, while Windows 10 users may learn how to install a Bash shell and the basics of using it at “How to Install and Use the Linux Bash Shell on Windows 10”. Once you’re in a terminal window, you can clone the TEI repos thus: git clone git@github.com:TEIC/TEI.git and git clone git@github.com:TEIC/Stylesheets.git It’s probably a good idea to keep these side-by-side. I put mine in a directory called: /Users/hcayless/Development/TEIC. As you will see, it’s a good idea to do this somewhere under the Users directory, whether you’re on Mac or Windows. If you’re running Ubuntu or some other Linux, you can put them where you like. Let’s assume you’ve got working copies of the TEI and Stylesheets repos, and that you’ve made some changes you’d like to test before you push them back up to GitHub and make them available to everyone. The TEI has set up a pre-built test environment in Docker that you can use. First, you should get Docker Community Edition (CE). On a Mac, go to , on Windows, , and on Linux, choose your specific platform here: . Follow Docker’s “Get Started” instructions for your installation to configure Docker and include the TEI repositories in your Docker container. Once you have Docker installed and set up, you can run docker pull teic/teidev-docker to grab a copy of the pre-built image. Now you’re ready to run your test environment. You’ll need a couple of pieces of information for Docker: the location of your repositories and your timezone. You can look up your timezone at Wikipedia. You need it because the default timezone of the container is UTC, which will lead to strange warnings when you run the builds unless you actually happen to be in sync with UTC, because the local time of your computer will differ from that set in the container. The directory containing your repositories will be mapped to a directory in the container (which is why it’s easier to put them side-by-side). You’ll run the test container with a command like: docker run --name tei -v /Users/hcayless/Development/TEIC:/tei -it -e TZ=America/New_York teic/teidev-docker which will put you in a Bash shell inside the container (named 'tei'), at the root directory. The directory on your local file system where you cloned the TEI and Stylesheets repos is mapped to /tei in the container (that’s the part after -v above). If you then do cd tei and then ls, you should see the repos you cloned above. There’s one more piece of work to be done, and that’s to tell the Guidelines build process where it can find your copy of the Stylesheets. You do that by adding a local.mk file in TEI/P5. So, (from /tei) do cd TEI/P5 and then echo "XSL=/tei/Stylesheets" > local.mk. Now you can build things! And, what’s more, you can work on the Guidelines and Stylesheets in your regular environment, and test them in Docker. The Docker command above will create a container named “tei”, which you can return to later. Because it runs a Bash terminal, you can exit it by typing exit at the command prompt, and that will stop the container. You can restart it with a command like docker start -ai tei, which will start the container and attach your terminal to it, with whatever state it was in when you left it. You may want to alias a simple command like teidocker to docker start -ai tei. To build the HTML version of the Guidelines, for example, you can run (in /tei/TEI/P5) make html-web, and after the process finishes, you’ll have a directory called “Guidelines-web” in your P5 directory. Outside your Docker shell, you can browse to this folder, find the index.html file, and open it in a browser. “Make” is a program typically used for compiling programs, but it’s also very useful as a kind of generic batch scripting tool, which is how it’s being used here. In the Guidelines, you’ll typically want to run Make inside the P5/ directory and in the Stylesheets, you’ll want to run it at the top of the repo (in Stylesheets/. You can also run Make in any directory that contains a Makefile. Note that the targets may vary. Running make inside Stylesheets/Test is pretty much the same as running make test one level up. You can also run individual test targets if there’s a particular set of tests you want to troubleshoot (e.g. make test-oddity in Stylesheets/Test to test ODD-conversion methods). The targets are all defined in the Makefiles. The Using the TEI GitHub Repository document has more detail on all the processes you can run, and very meager information on how to get set up to run them—but you just bypassed all that. Besides the make targets listed there, both the TEI and Stylesheets repos have make test targets which get run by Jenkins when you push to GitHub. These are both good ways to check your code before pushing. Make does lots of things when you run any of these targets, but all of them should finish with a “BUILD SUCCESSFUL” message. If there’s a problem, you’ll get a failure message, hopefully with some indication of what went wrong. If you’ve run a build target, you probably want to run a make clean before doing it again to make sure files that were generated during the last run don’t interfere with your next build (Make tries not to repeat itself, so if it finds existing build artifacts, it won’t rebuild them). Targets can be put together, so you can do make clean test, and it will clean things up before running the test target. When you run the tests and other build targets, you’ll see masses of text written out, most of which can be ignored. If one of the processes errors out, Make should stop running, so the last thing in your terminal should tell you what happened. This may not be a very useful message, so you might need to isolate the command that Make ran and run it yourself to see the error messages. In the Stylesheets, errors are often in the form of differences between the expected output of certain tests and the actual output. Test failures here aren’t necessarily errors—if you changed something to do with ODD compilation or schema generation, your new output might be correct but different from the old. When this happens, you can copy the new output from the Test/ directory into Test/expected-results. You’ll want to be a bit careful that your new output is actually correct, of course, because now the test will pass even if it’s not really working, because all it’s checking is whether the test output is the same as what it expects. Good luck and happy testing!