Using YAML in C++

YAML stands for “YAML Ain’t Markup Language”.  It is a “human friendly data serialization standard for all programming languages”.  What this means is that a human can read the files you write in YAML, and there are libraries and packages in almost every language that can also parse these files.  It’s a little bit more formal way to do parameter files and input files for models, since all the reading and error catching is provided by a library instead of by lines and lines of tedious code that you write.

I’m just playing around with this right now so I’ll share my notes here as I get it working.

The C++ libraries are available here.

1. Follow the instructions on the website to download the zip file.
2. The next instructions will either work on your Linux desktop or on the cluster.  They will probably work in Windows too, but I haven’t tried that yet.  I successfully ran the trial on my home computer running Ubuntu 11.10, but now I will replicate the process on the cluster.  Unzip the contents of the file on your computer of choice.
3. Follow the website instructions to create the build directory in your folder and navigate to it.
4. On the cluster, make sure to enable the program cmake by typing “module load cmake”.  Then, once you are in the build directory, you want to run cmake on the files in the outer directory, so type “cmake ..”
5. When cmake runs successfully, it generates a custom Makefile just for you and your system.  To run the makefile, simply type “make”.  You should see some colorful commands that show that the program has compiled successfully.
6. At the end, you’ll have a library called libyaml-cpp.a in your build directory.  Success!

Now we have a brand-new yaml-cpp library that contains all the functions you’ll need to parse yaml in your own program.  How do we test it out?  I’m glad you asked.

1. Create a new folder that’s outside of the yaml-cpp folder.  You can call it “program1” or some other name.  Into that folder, copy libyaml-cpp.a from your yaml-cpp/build/ folder.  Also navigate into the /include/ folder inside yaml-cpp, and you’ll find another folder called yaml-cpp.  This folder contains the headers for all the functions inside the library.  In your project folder, you can either copy it over as /include/yaml-cpp, or just as /yaml-cpp.  In my project, I just copied it as yaml-cpp, in order to not have too many folders laying around.
2. On the yaml-cpp site, try the monsters example at this page.  You’ll need a file called monsters.yaml, and the main cpp file, which I called test.cpp.  Here’s an important tip that it took me about a day (and help from the internet) to figure out: Only use spaces when indenting your blocks in the yaml file, not tabs!
3. Now compile your program.  You can use a command like this: “g++ -Wall -I. -g test.cpp -lyaml-cpp -L. -o monsterstest” which tells the compiler to find your include paths in the working folder (referred to with a dot), and to name the executable “monsterstest”.
4. Run the program using “monsterstest”  Did it work?  If so, great!

In a later post, I’ll give some example code that could be used to read objective titles, epsilons, constraints, model parameters, and so forth from a yaml file.  My idea is to have a master yaml file that contains all the parameters for a run.  The yaml can then be read by script programs that write input text files, java classes, or anything else you’d like.  The yaml will also be accessible to the C++ wrapper that interfaces with MOEAframework, and it can even be used directly by your simulation model.  This will give the user a lot of control, in a format that is flexible and fairly easy to use.  But more on that later!