# SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-or-later
# SPDX-FileCopyrightText: Bradley M. Bell <bradbell@seanet.com>
# SPDX-FileContributor: 2003-22 Bradley M. Bell
# ----------------------------------------------------------------------------

{xrst_begin download}
{xrst_spell
   gh
   github
   grep
   gz
   htm
   mhelp
   omhelp
   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 ``doc`` directory
and do not have the ``git`` information.
They are intended for re-distribution.

Documentation
=============
The documentation at the web address
https://coin-or.github.io/CppAD is for the
most recent version of CppAD.
You can get the documentation
for an other versions of CppAD.
To do so, in the distribution directory execute the following commands:
::

   git checkout gh-pages
   git log > junk.log

The file ``junk.log`` will contain the git *hash* codes
for different version of the documentation along with the date.
Select the *hash* for the version you are using, execute the command

   ``git checkout`` *hash*

You can then view documentation for version you are using by opening the file
``doc/index.html`` in a web browser.

Building Documentation
======================
The documentation for CppAD can be built, from a clone of the git repository,
using `OMhelp <http://www.seanet.com/~bradbell/omhelp/>`_.
You will need to install the ``omhelp`` command so that
::

   which omhelp

shows it is in your path.
Once you have done this,
in the distribution directory execute the following command:

   ``bin/run_omhelp.sh htm``

You can then view documentation for version you are using by opening the file
``doc/index.html`` in a web browser.

{xrst_end download}
