-----------------------------------------------
lines 6-123 of file: xrst/install/download.xrst
-----------------------------------------------

{xrst_begin download}
{xrst_spell
   dev
   github
   grep
   gz
   txt
   yyyy
}

Download The CppAD Source Code
##############################

Purpose
*******
CppAD is an include file library and you therefore need the source
code to use it.
This section discusses how to download the different versions of CppAD.

Distribution Directory
**********************
We refer to the CppAD source directory created by the download instructions
below as the distribution directory.
As a check, the distribution directory contains the file
``include/cppad/cppad.hpp`` .

Version
*******
A CppAD *version* number has the following fields:
*yyyy* is four decimal digits denoting a year,
*mm* is two decimal digits denoting a month,
and *dd* is two decimal digits denoting a day.
For example *version*  = 20160101 corresponds to January 1, 2016.

Release
*******
Special versions corresponding to the beginning of each year
have *dd* equal to zero.
These version numbers are combined with release numbers denoted by
*rel* .
Higher release numbers correspond to more bug fixes.
For example
*version* . *rel*  = 20160000.0 corresponds to the first release
of the version for 2016,
``20160000.1`` corresponds to the first bug fix for 2016.
The compressed archive names on the github
`releases <https://github.com/coin-or/CppAD/releases>`_ page
are named *version* . *rel* . ``tar.gz`` .
Before 2019,
these archives correspond to the Eclipse Public License Version 1
license and do not include the documentation.
Starting in 2019,
these archives correspond to the EPL 2.0 or (GPL 2.0 or later) license and
a separate compressed archive is available
on the releases page with name *version* . ``doc.tar.gz`` .

Git
***
CppAD source code development is current done using ``git``
You can a git clone of the current version using the command

   ``git clone https://github.com/coin-or/CppAD.git cppad.git``

This procedure requires that
the `git <https://en.wikipedia.org/wiki/Git_%28software%29>`_
is installed on your system.

Version
=======
After downloading the source code,
and changing into the distribution directory,
use the following command to determine the corresponding
:ref:`download@Version` :
::

   grep '^SET(cppad_version' CMakeLists.txt

Use the following command to determine the git *hash* code
corresponding to this version:
::

   git show-ref | grep 'refs/heads/master'

You can get an old version using the command

   ``git checkout -q`` *hash*

You can check the corresponding version number using the command
::

   grep '^SET(cppad_version' CMakeLists.txt

Compressed Archives
===================
You can build a compressed archive, from a clone of the git repository,
using the script ``bin/package.sh`` .
These archives have the documentation in the ``build/html`` directory
and do not have the ``git`` information.
They are intended for re-distribution.

Building Documentation
======================
If you install `xrst <https://xrst.readthedocs.io/latest/>`_ ,
you can build the documentation for CppAD,
and include any changes you make.
In the distribution directory execute the following command

| |tab|   ``bin/run_xrst.sh`` *dev*

where *dev* is ``-dev`` or ``+dev`` .
If you use ``+dev`` the developer documentation will be included.

You can then view documentation that you built by opening the
following file in a web browser::

   build/html/index.html

{xrst_end download}