contrib/libxo/doc/getting.rst

   1
   2 .. index:: Getting libxo
   3
   4 Getting libxo
   5 =============
   6
   7 libxo now ships as part of the FreeBSD Operating System (as of Release
   8 11).
   9
  10 libxo source code lives on github:
  11
  12   https://github.com/Juniper/libxo
  13
  14 The latest release of libxo is available at:
  15
  16   https://github.com/Juniper/libxo/releases
  17
  18 We're using `Semantic Versioning`_ to number our releases.  libxo is
  19 open source, distributed under the BSD license.  We follow the
  20 branching scheme from `A Successful Git Branching Model`_:
  21 we do development under the "*develop*" branch, and release from
  22 the "*master*" branch.  To clone a developer tree, run the following
  23 command::
  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
  31 Issues, problems, and bugs should be directly to the issues page on
  32 our github site.
  33
  34 Downloading libxo Source Code
  35 -----------------------------
  36
  37 You can retrieve the source for libxo in two ways:
  38
  39 A. 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
  58 B. 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
  80 Building libxo
  81 --------------
  82
  83 To build libxo, you'll need to set up the build, run the "*configure*"
  84 script, run the "*make*" command, and run the regression tests.
  85
  86 The following is a summary of the commands needed.  These commands are
  87 explained 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
  96 The following sections will walk through each of these steps with
  97 additional details and options, but the above directions should be all
  98 that's needed.
  99
 100 Setting up the build
 101 ~~~~~~~~~~~~~~~~~~~~
 102
 103 .. admonition: Note
 104
 105    If you downloaded a distfile, you can skip this step.
 106
 107 Run the "*setup.sh*" script to set up the build.  This script runs the
 108 "*autoreconf*" command to generate the "*configure*" script and other
 109 generated files::
 110
 111     sh bin/setup.sh
 112
 113 Note: We're are currently using autoreconf version 2.69.
 114
 115 Running the "configure" Script
 116 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 117
 118 Configure (and autoconf in general) provides a means of building
 119 software in diverse environments.  Our configure script supports
 120 a set of options that can be used to adjust to your operating
 121 environment. Use "`configure --help`" to view these options.
 122
 123 We use the "*build*" directory to keep object files and generated files
 124 away from the source tree.
 125
 126 To run the configure script, change into the "*build*" directory, and
 127 run the "*configure*" script.  Add any required options to the
 128 "`../configure`" command line::
 129
 130     cd build
 131     ../configure
 132
 133 Expect to see the "*configure*" script generate the following error::
 134
 135     /usr/bin/rm: cannot remove `libtoolT': No such file or directory
 136
 137 This error is harmless and can be safely ignored.
 138
 139 By default, libxo installs architecture-independent files, including
 140 extension library files, in the /usr/local directories. To specify an
 141 installation prefix other than /usr/local for all installation files,
 142 include the --prefix=prefix option and specify an alternate
 143 location. To install just the extension library files in a different,
 144 user-defined location, include the "*--with-extensions-dir=dir*" option
 145 and specify the location where the extension libraries will live::
 146
 147     cd build
 148     ../configure [OPTION]... [VAR=VALUE]...
 149
 150 Running the "make" Command
 151 ++++++++++++++++++++++++++
 152
 153 Once the "*configure*" script is run, build the images using the
 154 "`make`" command::
 155
 156     make
 157
 158 Running the Regression Tests
 159 ++++++++++++++++++++++++++++
 160
 161 libxo includes a set of regression tests that can be run to ensure
 162 the software is working properly.  These test are optional, but will
 163 help determine if there are any issues running libxo on your
 164 machine.  To run the regression tests::
 165
 166     make test
 167
 168 Installing libxo
 169 ~~~~~~~~~~~~~~~~
 170
 171 Once 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
 173 the installation directory, simply issue the command::
 174
 175     make install
 176
 177 If you are not the "*root*" user and are using the "*sudo*" package, use::
 178
 179     sudo make install
 180
 181 Verify 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