1 2.. index:: Getting libxo 3 4Getting libxo 5============= 6 7libxo now ships as part of the FreeBSD Operating System (as of Release 811). 9 10libxo source code lives on github: 11 12 https://github.com/Juniper/libxo 13 14The latest release of libxo is available at: 15 16 https://github.com/Juniper/libxo/releases 17 18We're using `Semantic Versioning`_ to number our releases. libxo is 19open source, distributed under the BSD license. We follow the 20branching scheme from `A Successful Git Branching Model`_: 21we do development under the "*develop*" branch, and release from 22the "*master*" branch. To clone a developer tree, run the following 23command:: 24 25 git clone https://github.com/Juniper/libxo.git -b develop 26 27.. _Semantic Versioning: http://semver.org/spec/v2.0.0.html 28.. _A Successful Git Branching Model: 29 http://nvie.com/posts/a-successful-git-branching-model 30 31Issues, problems, and bugs should be directly to the issues page on 32our github site. 33 34Downloading libxo Source Code 35----------------------------- 36 37You can retrieve the source for libxo in two ways: 38 39A. Use a "distfile" for a specific release. We use github to maintain 40 our releases. Visit the `release page`_ to see the list of 41 releases. To download the latest, look for the release witeh the 42 green "Latest release" button and the green "libxo-RELEASE.tar.gz" 43 button under that section. 44 45.. _release page: https://github.com/Juniper/libxo/releases 46 47 After downloading that release's distfile, untar it as follows:: 48 49 tar -zxf libxo-RELEASE.tar.gz 50 cd libxo-RELEASE 51 52 .. admonition:: Solaris Users 53 54 Note: for Solaris users, your "`tar`" command lacks the "-z" flag, 55 so you'll need to substitute "`gzip -dc $file | tar xf -`" instead 56 of "`tar -zxf $file`". 57 58B. Use the current build from github. This gives you the most recent 59 source code, which might be less stable than a specific release. To 60 build libxo from the git repo:: 61 62 git clone https://github.com/Juniper/libxo.git 63 cd libxo 64 65 .. admonition:: Be Aware 66 67 The github repository does **not** contain the files generated by 68 "*autoreconf*", with the notable exception of the "*m4*" directory. 69 Since these files (depcomp, configure, missing, install-sh, etc) are 70 generated files, we keep them out of the source code repository. 71 72 This means that if you download the a release distfile, these files 73 will be ready and you'll just need to run "configure", but if you 74 download the source code from svn, then you'll need to run 75 "*autoreconf*" by hand. This step is done for you by the "*setup.sh*" 76 script, described in the next section. 77 78.. _building: 79 80Building libxo 81-------------- 82 83To build libxo, you'll need to set up the build, run the "*configure*" 84script, run the "*make*" command, and run the regression tests. 85 86The following is a summary of the commands needed. These commands are 87explained in detail in the rest of this section:: 88 89 sh bin/setup.sh 90 cd build 91 ../configure 92 make 93 make test 94 sudo make install 95 96The following sections will walk through each of these steps with 97additional details and options, but the above directions should be all 98that's needed. 99 100Setting up the build 101~~~~~~~~~~~~~~~~~~~~ 102 103.. admonition: Note 104 105 If you downloaded a distfile, you can skip this step. 106 107Run the "*setup.sh*" script to set up the build. This script runs the 108"*autoreconf*" command to generate the "*configure*" script and other 109generated files:: 110 111 sh bin/setup.sh 112 113Note: We're are currently using autoreconf version 2.69. 114 115Running the "configure" Script 116~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 117 118Configure (and autoconf in general) provides a means of building 119software in diverse environments. Our configure script supports 120a set of options that can be used to adjust to your operating 121environment. Use "`configure --help`" to view these options. 122 123We use the "*build*" directory to keep object files and generated files 124away from the source tree. 125 126To run the configure script, change into the "*build*" directory, and 127run the "*configure*" script. Add any required options to the 128"`../configure`" command line:: 129 130 cd build 131 ../configure 132 133Expect to see the "*configure*" script generate the following error:: 134 135 /usr/bin/rm: cannot remove `libtoolT': No such file or directory 136 137This error is harmless and can be safely ignored. 138 139By default, libxo installs architecture-independent files, including 140extension library files, in the /usr/local directories. To specify an 141installation prefix other than /usr/local for all installation files, 142include the --prefix=prefix option and specify an alternate 143location. To install just the extension library files in a different, 144user-defined location, include the "*--with-extensions-dir=dir*" option 145and specify the location where the extension libraries will live:: 146 147 cd build 148 ../configure [OPTION]... [VAR=VALUE]... 149 150Running the "make" Command 151++++++++++++++++++++++++++ 152 153Once the "*configure*" script is run, build the images using the 154"`make`" command:: 155 156 make 157 158Running the Regression Tests 159++++++++++++++++++++++++++++ 160 161libxo includes a set of regression tests that can be run to ensure 162the software is working properly. These test are optional, but will 163help determine if there are any issues running libxo on your 164machine. To run the regression tests:: 165 166 make test 167 168Installing libxo 169~~~~~~~~~~~~~~~~ 170 171Once the software is built, you'll need to install libxo using the 172"`make install`" command. If you are the root user, or the owner of 173the installation directory, simply issue the command:: 174 175 make install 176 177If you are not the "*root*" user and are using the "*sudo*" package, use:: 178 179 sudo make install 180 181Verify the installation by viewing the output of "`xo --version`":: 182 183 % xo --version 184 libxo version 0.3.5-git-develop 185 xo version 0.3.5-git-develop 186