From b680aa1e70ae616a507c334896bd1152feef30fa Mon Sep 17 00:00:00 2001 From: Jürgen Knödlseder Date: Fri, 19 Jan 2018 16:52:20 +0100 Subject: [PATCH] Reorganise ctools installation documentation and add information about conda and binary installs --- doc/source/admin/download.rst | 267 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- doc/source/admin/index.rst | 4 +++- doc/source/admin/install_binary.rst | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/source/admin/install_conda.rst | 10 ++++++---- doc/source/admin/install_devel.rst | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/source/admin/install_source.rst | 15 ++++++++++----- doc/source/admin/macosx-disk-image.jpg | Bin 0 -> 92431 bytes doc/source/admin/macosx-installed.jpg | Bin 0 -> 114032 bytes doc/source/admin/macosx-installer.jpg | Bin 0 -> 94888 bytes doc/source/admin/macosx-invalid-cert.jpg | Bin 0 -> 116269 bytes doc/source/admin/macosx-open-package.jpg | Bin 0 -> 139682 bytes doc/source/admin/macosx-unidentified.jpg | Bin 0 -> 87356 bytes doc/source/admin/release_history/1.5.rst | 2 +- doc/source/admin/release_history/index.rst | 18 +++++------------- 14 files changed, 269 insertions(+), 201 deletions(-) create mode 100644 doc/source/admin/install_binary.rst create mode 100644 doc/source/admin/install_devel.rst create mode 100644 doc/source/admin/macosx-disk-image.jpg create mode 100644 doc/source/admin/macosx-installed.jpg create mode 100644 doc/source/admin/macosx-installer.jpg create mode 100644 doc/source/admin/macosx-invalid-cert.jpg create mode 100644 doc/source/admin/macosx-open-package.jpg create mode 100644 doc/source/admin/macosx-unidentified.jpg diff --git a/doc/source/admin/download.rst b/doc/source/admin/download.rst index 55d734d..9544a18 100644 --- a/doc/source/admin/download.rst +++ b/doc/source/admin/download.rst @@ -3,16 +3,6 @@ Download ======== -ctools can be obtained in form of releases or directly from the git -development repository. Prefer a release if you intend using ctools -for production (and publications). Clone the code from git if you need -the most recent code that implements new features and corrects known -bugs. - - -Releases --------- - The latest ctools release is ``ctools-1.4.3`` (31 October 2017). Below a table of ctools releases. Please read the :ref:`sec_release` to @@ -21,170 +11,93 @@ learn more about new features and corrected bugs in a given release. .. warning:: At this stage of the project there is a strict link between the ctools and gammalib versions. Please make sure that you have the corresponding gammalib - version installed before installing ctools. The Mac OS X packages comprise - both ctools and gammalib. - -.. list-table:: - :header-rows: 1 - :widths: 5 5 10 - - * - ctools - - gammalib - - Mac OS X package - * - `1.4.3 `_ - - `1.4.3 `_ - - `ctools-1.4.3-macosx10.7.dmg `_ - * - `1.4.2 `_ - - `1.4.2 `_ - - `ctools-1.4.2-macosx10.7.dmg `_ - * - `1.4.1 `_ - - `1.4.1 `_ - - `ctools-1.4.1-macosx10.7.dmg `_ - * - `1.4.0 `_ - - `1.4.0 `_ - - `ctools-1.4.0-macosx10.7.dmg `_ - * - `1.3.1 `_ - - `1.3.1 `_ - - `ctools-1.3.1-macosx10.7.dmg `_ - * - `1.3.0 `_ - - `1.3.0 `_ - - `ctools-1.3.0-macosx10.7.dmg `_ - * - `1.2.1 `_ - - `1.2.0 `_ - - `ctools-1.2.1-macosx10.7.dmg `_ - * - `1.2.0 `_ - - `1.2.0 `_ - - `ctools-1.2.0-macosx10.7.dmg `_ - * - `1.1.0 `_ - - `1.1.0 `_ - - `ctools-1.1.0-macosx10.3.dmg `_ - * - `1.0.1 `_ - - `1.0.1 `_ - - `ctools-1.0.1-macosx10.3.dmg `_ - * - `1.0.0 `_ - - `1.0.0 `_ - - `ctools-1.0.0-macosx10.3.dmg `_ - * - `0.10.0 `_ - - `0.11.0 `_ - - `ctools-0.10.0-macosx10.3.dmg `_ - * - `0.9.0 `_ - - `0.10.0 `_ - - `ctools-0.9.1-macosx10.3.dmg `_ - * - `0.8.1 `_ - - `0.9.1 `_ - - `ctools-00-08-01-macosx10.3.dmg `_ - * - `0.8.0 `_ - - `0.9.0 `_ - - `ctools-00-08-00-macosx10.3.dmg `_ - * - `0.7.1 `_ - - `0.8.1 `_ - - `ctools-00-07-01-macosx10.3.dmg `_ - * - `0.7.0 `_ - - `0.8.0 `_ - - `ctools-00-07-00-macosx10.3.dmg `_ - * - `0.6.0 `_ - - `0.7.0 `_ - - `ctools-00-06-00-macosx10.3.dmg `_ - * - `0.5.1 `_ - - `0.6.2 `_ - - `ctools-00-05-01-macosx10.3.dmg `_ - * - `0.5.0 `_ - - `0.6.1 `_ - - `ctools-00-05-00-macosx10.3.dmg `_ - * - `0.4.0 `_ - - `0.5.0 `_ - - `ctools-00-04-00-macosx10.3.dmg `_ - * - `0.3.0 `_ - - `0.4.2 `_ - - `ctools-00-03-00-macosx10.3.dmg `_ - * - `0.2.5 `_ - - `0.4.11 `_ - - - * - `0.2.4 `_ - - `0.4.10 `_ - - - * - `0.2.3 `_ - - `0.4.9 `_ - - - * - `0.2.1 `_ - - `0.4.7 `_ - - - - -Development release -------------------- - -The current ctools development release is ``ctools-1.5.0.dev1``. -This release reflects the status of the current ``devel`` branch of -the ctools git repository. - -* `Mac OS X binary package `_ (Mac OS X 10.7+) -* `GammaLib `_ source code tarball -* `ctools `_ source code tarball - - -Git repository --------------- - -To clone the gammalib and ctools source codes, type - -.. code-block:: bash - - $ git clone https://cta-gitlab.irap.omp.eu/gammalib/gammalib.git - $ git clone https://cta-gitlab.irap.omp.eu/ctools/ctools.git - -This will create directories named gammalib and ctools under the current -working directory that will contain the gammalib and ctools source code. -In case that the cloning does not work you may try adding - -.. code-block:: bash - - $ export GIT_SSL_NO_VERIFY=true - -or - -.. code-block:: bash - - $ git config --global http.sslverify "false" - -before retrieving the code. -Before you will be able to compile the code you need to generate the -configuration file using the ``autogen.sh`` script. -Also make sure that you're actually on the devel branch of the git -repository. GammaLib and ctools can be compiled and configured using -the following command sequence (the code will be installed into the -``/usr/local/gamma`` directory): - -.. code-block:: bash - - $ cd gammalib - $ git checkout devel - $ ./autogen.sh - $ ./configure - $ make - $ make check - $ sudo make install - $ export GAMMALIB=/usr/local/gamma - $ source $GAMMALIB/bin/gammalib-init.sh - $ cd ../ctools - $ git checkout devel - $ ./autogen.sh - $ ./configure - $ make - $ make check - $ sudo make install - $ export CTOOLS=/usr/local/gamma - $ source $CTOOLS/bin/ctools-init.sh - -Please read the :ref:`sec_install` section if you need more information on -how to install ctools. - -.. note:: - - You need `swig `_ on your system to build the - Python wrappers when you get the code from Git. Python wrappers are - not stored in the Git repository but are built using - `swig `_ from interface files located in the - pyext folder. However, you do not need `swig `_ - when fetching a release as the Python wrappers are bundled with the - release tarballs. + version installed before installing ctools. The Mac OS X binary packages + comprise both ctools and gammalib. + +.. + + .. list-table:: + :header-rows: 1 + :widths: 5 5 10 + + * - ctools + - gammalib + - Mac OS X (10.7+) binary disk image + * - `1.4.3 `_ + - `1.4.3 `_ + - `ctools-1.4.3-macosx10.7.dmg `_ + * - `1.4.2 `_ + - `1.4.2 `_ + - `ctools-1.4.2-macosx10.7.dmg `_ + * - `1.4.1 `_ + - `1.4.1 `_ + - `ctools-1.4.1-macosx10.7.dmg `_ + * - `1.4.0 `_ + - `1.4.0 `_ + - `ctools-1.4.0-macosx10.7.dmg `_ + * - `1.3.1 `_ + - `1.3.1 `_ + - `ctools-1.3.1-macosx10.7.dmg `_ + * - `1.3.0 `_ + - `1.3.0 `_ + - `ctools-1.3.0-macosx10.7.dmg `_ + * - `1.2.1 `_ + - `1.2.0 `_ + - `ctools-1.2.1-macosx10.7.dmg `_ + * - `1.2.0 `_ + - `1.2.0 `_ + - `ctools-1.2.0-macosx10.7.dmg `_ + * - `1.1.0 `_ + - `1.1.0 `_ + - `ctools-1.1.0-macosx10.3.dmg `_ + * - `1.0.1 `_ + - `1.0.1 `_ + - `ctools-1.0.1-macosx10.3.dmg `_ + * - `1.0.0 `_ + - `1.0.0 `_ + - `ctools-1.0.0-macosx10.3.dmg `_ + * - `0.10.0 `_ + - `0.11.0 `_ + - `ctools-0.10.0-macosx10.3.dmg `_ + * - `0.9.0 `_ + - `0.10.0 `_ + - `ctools-0.9.1-macosx10.3.dmg `_ + * - `0.8.1 `_ + - `0.9.1 `_ + - `ctools-00-08-01-macosx10.3.dmg `_ + * - `0.8.0 `_ + - `0.9.0 `_ + - `ctools-00-08-00-macosx10.3.dmg `_ + * - `0.7.1 `_ + - `0.8.1 `_ + - `ctools-00-07-01-macosx10.3.dmg `_ + * - `0.7.0 `_ + - `0.8.0 `_ + - `ctools-00-07-00-macosx10.3.dmg `_ + * - `0.6.0 `_ + - `0.7.0 `_ + - `ctools-00-06-00-macosx10.3.dmg `_ + * - `0.5.1 `_ + - `0.6.2 `_ + - `ctools-00-05-01-macosx10.3.dmg `_ + * - `0.5.0 `_ + - `0.6.1 `_ + - `ctools-00-05-00-macosx10.3.dmg `_ + * - `0.4.0 `_ + - `0.5.0 `_ + - `ctools-00-04-00-macosx10.3.dmg `_ + * - `0.3.0 `_ + - `0.4.2 `_ + - `ctools-00-03-00-macosx10.3.dmg `_ + * - `0.2.5 `_ + - `0.4.11 `_ + - + * - `0.2.4 `_ + - `0.4.10 `_ + - + * - `0.2.3 `_ + - `0.4.9 `_ + - + * - `0.2.1 `_ + - `0.4.7 `_ + - diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index e38fafc..e343168 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -6,7 +6,9 @@ Getting ctools .. toctree:: :maxdepth: 1 - install_source install_conda + install_source + install_binary + install_devel download release_history/index diff --git a/doc/source/admin/install_binary.rst b/doc/source/admin/install_binary.rst new file mode 100644 index 0000000..21c7856 --- /dev/null +++ b/doc/source/admin/install_binary.rst @@ -0,0 +1,57 @@ +.. _sec_install_binary: + +Installing as binary package +============================ + +Mac OS X +-------- + +After :ref:`downloading the Mac OS X binary disk image ` +double-click on the image to mount the disk + +.. image:: macosx-disk-image.jpg + :height: 300px + :alt: Mac OS X binary disk image + :align: center + +Now open the installer package by right-clicking (ctrl-click) on the installer +package icon. This allows to install a software package with an invalid +certificate (ctools has so far no Apple certificate) + +.. image:: macosx-open-package.jpg + :height: 300px + :alt: Open installer package + :align: center + +A window will show up, warning that the package comes from an unidentified +developer. Click on ``Open`` to continue. + +.. image:: macosx-unidentified.jpg + :height: 200px + :alt: Unidentified developer warning + :align: center + +Now the installer opens, warning that the package has been signed with an +invalid certificate. Click on ``Continue`` to proceed. + +.. image:: macosx-invalid-cert.jpg + :height: 300px + :alt: Invalid certificate warning + :align: center + +Follow now the installer instructions by clicking on ``Continue``. As the +software will be installed in ``/usr/local/gamma`` the installer will ask +you for the ``root`` password on your machine. + +.. image:: macosx-installer.jpg + :height: 300px + :alt: Installer introduction + :align: center + +At the end you should see a window like this: + +.. image:: macosx-installed.jpg + :height: 300px + :alt: Installer summary + :align: center + diff --git a/doc/source/admin/install_conda.rst b/doc/source/admin/install_conda.rst index d05cec8..f5d3e7e 100644 --- a/doc/source/admin/install_conda.rst +++ b/doc/source/admin/install_conda.rst @@ -1,7 +1,7 @@ .. _sec_install_conda: -Installing via conda -==================== +Installing via Anaconda +======================= `Anaconda `_ (you can also use `Miniconda `_ for a smaller footprint) is a @@ -11,7 +11,8 @@ Anaconda Python version. An Anaconda Python installation is completely separate from any existing system wide or user space Python installation, so Anaconda can be tested without the fear of breaking an existing installation. -Anaconda works on most systems without root access! +**Anaconda ctools packages exist for Mac OS X and Linux distributions. Windows +is not supported.** Installing @@ -30,7 +31,8 @@ Installing - We strongly recommend to work with separate Anaconda environments, and especially not use the special root environment (that is used for all conda commands and environment manipulations, package installations etc.) for - anything besides updating the conda package itself (if necessary): + anything besides updating the conda package itself. For example create + a ``myenv`` environment as follows: .. code-block:: bash diff --git a/doc/source/admin/install_devel.rst b/doc/source/admin/install_devel.rst new file mode 100644 index 0000000..29389d4 --- /dev/null +++ b/doc/source/admin/install_devel.rst @@ -0,0 +1,97 @@ +.. _sec_install_devel: + +Installing the development version +================================== + +The current development version of the code can be downloaded as source +tarballs, Mac OS X binaries, or directly from the `Git `_ +repository. + +The current ctools development release is ``ctools-1.5.0.dev1``. + + +Source tarballs +--------------- + +Download the source tarballs from the following links + +- `ctools `_ +- `GammaLib `_ + +and follow the instructions on :ref:`sec_install_source`. + + +Binary packages +--------------- + +Download the installer image from the following link + +- `Mac OS X (10.7+) `_ + +and follow the instructions on :ref:`sec_install_binary`. + + +Git repository +-------------- + +To clone the gammalib and ctools source codes, type + +.. code-block:: bash + + $ git clone https://cta-gitlab.irap.omp.eu/gammalib/gammalib.git + $ git clone https://cta-gitlab.irap.omp.eu/ctools/ctools.git + +This will create directories named gammalib and ctools under the current +working directory that will contain the gammalib and ctools source code. +In case that the cloning does not work you may try adding + +.. code-block:: bash + + $ export GIT_SSL_NO_VERIFY=true + +or + +.. code-block:: bash + + $ git config --global http.sslverify "false" + +before retrieving the code. +Before you will be able to compile the code you need to generate the +configuration file using the ``autogen.sh`` script. +Also make sure that you're actually on the devel branch of the git +repository. GammaLib and ctools can be compiled and configured using +the following command sequence (the code will be installed into the +``/usr/local/gamma`` directory): + +.. code-block:: bash + + $ cd gammalib + $ git checkout devel + $ ./autogen.sh + $ ./configure + $ make + $ make check + $ sudo make install + $ export GAMMALIB=/usr/local/gamma + $ source $GAMMALIB/bin/gammalib-init.sh + $ cd ../ctools + $ git checkout devel + $ ./autogen.sh + $ ./configure + $ make + $ make check + $ sudo make install + $ export CTOOLS=/usr/local/gamma + $ source $CTOOLS/bin/ctools-init.sh + +Please read the :ref:`sec_install_source` section if you need more information +on how to install ctools. + +.. note:: + You need `swig `_ on your system to build the + Python wrappers when you get the code from Git. Python wrappers are + not stored in the Git repository but are built using + `swig `_ from interface files located in the + pyext folder. However, you do not need `swig `_ + when fetching a release as the Python wrappers are bundled with the + release tarballs. diff --git a/doc/source/admin/install_source.rst b/doc/source/admin/install_source.rst index a7ea843..b35f262 100644 --- a/doc/source/admin/install_source.rst +++ b/doc/source/admin/install_source.rst @@ -1,7 +1,14 @@ -.. _sec_compiling_source: +.. _sec_install_source: + +Installing from source code +=========================== + +Compiling ctools from source is the recommended method to install the package +in case that you do not use Anaconda (if you use Anaconda, please follow +the instructions at :ref:`sec_install_conda`, and better do not try to compile +the source code against your Anaconda Python installation). You also need to +compile from source if you want to use the development version of ctools. -Compiling from source -===================== Before you start ---------------- @@ -24,8 +31,6 @@ software: is highly recommended to enable dynamic scripting of ctools and developing and using of cscripts. -No system administrator privileges are needed to install ctools. - Installing GammaLib ------------------- diff --git a/doc/source/admin/macosx-disk-image.jpg b/doc/source/admin/macosx-disk-image.jpg new file mode 100644 index 0000000..dda28e7 Binary files /dev/null and b/doc/source/admin/macosx-disk-image.jpg differ diff --git a/doc/source/admin/macosx-installed.jpg b/doc/source/admin/macosx-installed.jpg new file mode 100644 index 0000000..abd1a83 Binary files /dev/null and b/doc/source/admin/macosx-installed.jpg differ diff --git a/doc/source/admin/macosx-installer.jpg b/doc/source/admin/macosx-installer.jpg new file mode 100644 index 0000000..dd02491 Binary files /dev/null and b/doc/source/admin/macosx-installer.jpg differ diff --git a/doc/source/admin/macosx-invalid-cert.jpg b/doc/source/admin/macosx-invalid-cert.jpg new file mode 100644 index 0000000..4a7f2f2 Binary files /dev/null and b/doc/source/admin/macosx-invalid-cert.jpg differ diff --git a/doc/source/admin/macosx-open-package.jpg b/doc/source/admin/macosx-open-package.jpg new file mode 100644 index 0000000..f3faee6 Binary files /dev/null and b/doc/source/admin/macosx-open-package.jpg differ diff --git a/doc/source/admin/macosx-unidentified.jpg b/doc/source/admin/macosx-unidentified.jpg new file mode 100644 index 0000000..4b25e42 Binary files /dev/null and b/doc/source/admin/macosx-unidentified.jpg differ diff --git a/doc/source/admin/release_history/1.5.rst b/doc/source/admin/release_history/1.5.rst index d3977cc..5d6249e 100644 --- a/doc/source/admin/release_history/1.5.rst +++ b/doc/source/admin/release_history/1.5.rst @@ -38,7 +38,7 @@ Improvements * [`2260 `_] - Handle On/Off observations by :ref:`cspull` * [`2237 `_] - - Add ``statistic`` parameters to :ref:`ctbutterfly`, :ref:`cterror`, + Add ``statistic`` parameter to :ref:`ctbutterfly`, :ref:`cterror`, :ref:`cttsmap`, :ref:`ctulimit`, :ref:`cslightcrv`, :ref:`csphasecrv`, :ref:`cspull`, :ref:`cssens`, :ref:`csspec`, :ref:`cstsdist` and :ref:`cstsmapsplit` diff --git a/doc/source/admin/release_history/index.rst b/doc/source/admin/release_history/index.rst index f079854..b969bd1 100644 --- a/doc/source/admin/release_history/index.rst +++ b/doc/source/admin/release_history/index.rst @@ -3,29 +3,21 @@ Release History =============== -Major releases: - .. toctree:: :maxdepth: 1 ctools 1.5 <1.5> - ctools 1.4 <1.4> - ctools 1.3 <1.3> - ctools 1.2 <1.2> - ctools 1.1 <1.1> - ctools 1.0 <1.0> - -Bug fix releases: - -.. toctree:: - :maxdepth: 1 - ctools 1.4.3 <1.4.3> ctools 1.4.2 <1.4.2> ctools 1.4.1 <1.4.1> + ctools 1.4 <1.4> ctools 1.3.1 <1.3.1> + ctools 1.3 <1.3> ctools 1.2.1 <1.2.1> + ctools 1.2 <1.2> + ctools 1.1 <1.1> ctools 1.0.1 <1.0.1> + ctools 1.0 <1.0> For older ctools versions see `here `_. -- libgit2 0.21.4