+
+1_
+Overview
+
+libxo - A Library for Generating Text, XML, JSON, and HTML Output
+You want to prepare for the future, but you need to live in the present. You'd love a flying car, but need to get to work today. You want to support features like XML, JSON, and HTML rendering to allow integration with NETCONF, REST, and web browsers, but you need to make text output for command line users. And you don't want multiple code paths that can't help but get out of sync. None of this "if (xml) {... } else {...}" logic. And ifdefs are right out. But you'd really, really like all the fancy features that modern encoding formats can provide. libxo can help.
+The libxo library allows an application to generate text, XML, JSON, and HTML output using a common set of function calls. The application decides at run time which output style should be produced. The application calls a function "xo_emit" to product output that is described in a format string. A "field descriptor" tells libxo what the field is and what it means. Each field descriptor is placed in braces with a printf-like format string (Section 2.2):
+
+ xo_emit(" {:lines/%7ju} {:words/%7ju} "
+ "{:characters/%7ju} {d:filename/%s}\n",
+ linect, wordct, charct, file);
+ Each field can have a role, with the 'value' role being the default, and the role tells libxo how and when to render that field. Output can then be generated in various style, using the "‑‑libxo" option:
+
+ % wc /etc/motd
+ 25 165 1140 /etc/motd
+ % wc --libxo xml,pretty,warn /etc/motd
+ <wc>
+ <file>
+ <lines>25</lines>
+ <words>165</words>
+ <characters>1140</characters>
+ <filename>/etc/motd</filename>
+ </file>
+ </wc>
+ % wc --libxo json,pretty,warn /etc/motd
+ {
+ "wc": {
+ "file": [
+ {
+ "lines": 25,
+ "words": 165,
+ "characters": 1140,
+ "filename": "/etc/motd"
+ }
+ ]
+ }
+ }
+ % wc --libxo html,pretty,warn /etc/motd
+ <div class="line">
+ <div class="text"> </div>
+ <div class="data" data-tag="lines"> 25</div>
+ <div class="text"> </div>
+ <div class="data" data-tag="words"> 165</div>
+ <div class="text"> </div>
+ <div class="data" data-tag="characters"> 1140</div>
+ <div class="text"> </div>
+ <div class="data" data-tag="filename">/etc/motd</div>
+ </div>
+ Section Contents:
+ +
+
+1.1
+Getting libxo
+
+libxo lives on github as:
+https://github.com/Juniper/libxo
+The latest release of libxo is available at:
+https://github.com/Juniper/libxo/releases
+We are following the branching scheme from http://nvie.com/posts/a-successful-git-branching-model/ which means we will do development under the "develop" branch, and release from the "master" branch. To clone a developer tree, run the following command:
++ git clone https://github.com/Juniper/libxo.git -b develop +
We're using semantic release numbering, as defined in http://semver.org/spec/v2.0.0.html.
+libxo is open source, distributed under the BSD license. It shipped as part of the FreeBSD operating system starting with release 11.0.
+Issues, problems, and bugs should be directly to the issues page on our github site.
+Section Contents:
+ ++ +Downloading libxo Source Code +
+You can retrieve the source for libxo in two ways:
+A) Use a "distfile" for a specific release. We use github to maintain our releases. Visit github release page (https://github.com/Juniper/libxo/releases) to see the list of releases. To download the latest, look for the release with the green "Latest release" button and the green "libxo‑RELEASE.tar.gz" button under that section.
+After downloading that release's distfile, untar it as follows:
++ tar -zxf libxo-RELEASE.tar.gz + cd libxo-RELEASE +
[Note: for Solaris users, your "tar" command lacks the "‑z" flag, so you'll need to substitute "gzip -dc "file" | tar xf -" instead of "tar -zxf "file"".]
+B) Use the current build from github. This gives you the most recent source code, which might be less stable than a specific release. To build libxo from the git repo:
++ git clone https://github.com/Juniper/libxo.git + cd libxo +
_BE AWARE_: The github repository does _not_ contain the files generated by "autoreconf", with the notable exception of the "m4" directory. Since these files (depcomp, configure, missing, install-sh, etc) are generated files, we keep them out of the source code repository.
+This means that if you download the a release distfile, these files will be ready and you'll just need to run "configure", but if you download the source code from svn, then you'll need to run "autoreconf" by hand. This step is done for you by the "setup.sh" script, described in the next section.
++ +Building libxo +
+To build libxo, you'll need to set up the build, run the "configure" script, run the "make" command, and run the regression tests.
+The following is a summary of the commands needed. These commands are explained in detail in the rest of this section.
++ sh bin/setup.sh + cd build + ../configure + make + make test + sudo make install +
The following sections will walk thru each of these steps with additional details and options, but the above directions should be all that's needed.
+Section Contents:
+ ++ +Setting up the build +
+[If you downloaded a distfile, you can skip this step.]
+Run the "setup.sh" script to set up the build. This script runs the "autoreconf" command to generate the "configure" script and other generated files.
++ sh bin/setup.sh +
Note: We're are currently using autoreconf version 2.69.
++ +Running the "configure" Script +
+Configure (and autoconf in general) provides a means of building software in diverse environments. Our configure script supports a set of options that can be used to adjust to your operating environment. Use "configure --help" to view these options.
+We use the "build" directory to keep object files and generated files away from the source tree.
+To run the configure script, change into the "build" directory, and run the "configure" script. Add any required options to the "../configure" command line.
++ cd build + ../configure +
Expect to see the "configure" script generate the following error:
++ /usr/bin/rm: cannot remove `libtoolT': No such file or directory +
This error is harmless and can be safely ignored.
+By default, libxo installs architecture-independent files, including extension library files, in the /usr/local directories. To specify an installation prefix other than /usr/local for all installation files, include the --prefix=prefix option and specify an alternate location. To install just the extension library files in a different, user-defined location, include the --with-extensions-dir=dir option and specify the location where the extension libraries will live.
++ cd build + ../configure [OPTION]... [VAR=VALUE]... +
+ +Running the "make" command +
+Once the "configure" script is run, build the images using the "make" command:
++ make +
+ +Running the Regression Tests +
+libxo includes a set of regression tests that can be run to ensure the software is working properly. These test are optional, but will help determine if there are any issues running libxo on your machine. To run the regression tests:
++ make test +
+ +Installing libxo +
+Once the software is built, you'll need to install libxo using the "make install" command. If you are the root user, or the owner of the installation directory, simply issue the command:
++ make install +
If you are not the "root" user and are using the "sudo" package, use:
++ sudo make install +
Verify the installation by viewing the output of "xo --version":
++ % xo --version + libxo version 0.3.5-git-develop + xo version 0.3.5-git-develop +