Wrijupan Bhattacharyya / ctools

Commit 43d75977437bc2ceec0b5fc05403acb3d96f3665

Authored by Jürgen Knödlseder
1 parent 2f3e703f

Write ctools installation instructions based on existing html file.

Inline Side-by-side
Showing 1 changed file with 347 additions and 0 deletions
doc/source/user_manual/getting.rst 0 → 100644
  View file @43d7597
  1 +Getting the ctools
  2 +==================
  3 +
  4 +Before you start
  5 +----------------
  6 +
  7 +The procedure for building and installing ctools is modeled on GNU
  8 +software distributions. You will need the following to build the
  9 +software:
  10 +
  11 +- Up to TBD free disk space.
  12 +
  13 +- ANSI C++ compiler. ctools builds well using GNU g++.
  14 +
  15 +- make
  16 +
  17 +- gammalib (see next section).
  18 +
  19 +- Python, including the Python developer package that includes the
  20 + ``Python.h`` header files. Although ctools compiles without Python and/or
  21 + the Python developer package installed, compiling with Python support
  22 + is highly recommended to enable dynamic scripting of ctools and
  23 + developing and using of cscripts.
  24 +
  25 +No system administrator privileges are needed to install ctools.
  26 +
  27 +
  28 +Installing gammalib
  29 +-------------------
  30 +
  31 +ctools is built on top of gammalib, hence gammalib needs to be built,
  32 +installed and configured before ctools can be installed. In case that
  33 +ctools is already installed on your system you may skip reading this
  34 +section and continue with Section TBD that explains how to install ctools.
  35 +
  36 +You will need the following to build the gammalib:
  37 +
  38 +- About 100 MB of free disk space.
  39 +
  40 +- An ANSI C++ compiler. We recommend building GammaLib with the GNU g++
  41 + compiler.
  42 +
  43 +- GNU make
  44 +
  45 +- The cfitsio library for FITS file support together with the developer
  46 + package that includes the ``cfitsio.h`` header.
  47 +
  48 +- Python, including the Python developer package that includes the
  49 + ``Python.h`` header files. Although ctools compiles without Python and/or
  50 + the Python developer package installed, compiling with Python support
  51 + is highly recommended to enable dynamic scripting of ctools and
  52 + developing and using of cscripts.
  53 +
  54 +Furthermore it is recommended to have readline and ncurses installed (including
  55 +the developer packages)
  56 +
  57 +After downloading the gammalib tarball, save it in an appropriate location
  58 +(for example ``$HOME/builds``), and type
  59 +
  60 +.. code-block:: bash
  61 +
  62 + $ tar xvfz gammalib-00-08-00.tar.gz
  63 +
  64 +(the ``$`` symbol indicates the console prompt and is not part of the
  65 +command that you should type in).
  66 +
  67 +Step in the created directory using
  68 +
  69 +.. code-block:: bash
  70 +
  71 + $ cd gammalib-00-08-00
  72 +
  73 +and build, check and install gammalib by typing
  74 +
  75 +.. code-block:: bash
  76 +
  77 + $ ./configure
  78 + $ make
  79 + $ make check
  80 + $ make install
  81 +
  82 +The last step may require system administator privileges. In this case,
  83 +use
  84 +
  85 + $ sudo make install
  86 +
  87 +If you do not have system administrator privileges, change the install
  88 +directory by typing for example
  89 +
  90 +.. code-block:: bash
  91 +
  92 + $ ./configure --prefix=$HOME/gamma
  93 +
  94 +which then installs GammaLib in the ``gamma`` folder of your home
  95 +directory.
  96 +
  97 +
  98 +Setting up the GammaLib environment
  99 +-----------------------------------
  100 +
  101 +Before building and installing ctools, you have to configure GammaLib by
  102 +setting up some environment variables. This will be done automatically by
  103 +an initialisation script that is found in the ``bin`` directory of the
  104 +GammaLib directory (we call here "GammaLib directory" the directory into
  105 +which GammaLib has been installed). Assuming that you have installed
  106 +GammaLib in the default directory ``/usr/local/gamma`` you need to add the
  107 +following to your ``$HOME/.bashrc`` or ``$HOME/.profile`` script on a Linux
  108 +machine:
  109 +
  110 +.. code-block:: bash
  111 +
  112 + export GAMMALIB=/usr/local/gamma
  113 + source $GAMMALIB/bin/gammalib-init.sh
  114 +
  115 +If you use C shell or a variant then add the following to your
  116 +``$HOME/.cshrc`` or ``$HOME/.tcshrc`` script:
  117 +
  118 +.. code-block:: csh
  119 +
  120 + setenv GAMMALIB /usr/local/gamma
  121 + source $GAMMALIB/bin/gammalib-init.csh
  122 +
  123 +
  124 +Building ctools
  125 +---------------
  126 +
  127 +After downloading the ctools tarball, save it in an appropriate location
  128 +(for example ``$HOME/builds``), and type
  129 +
  130 +.. code-block:: bash
  131 +
  132 + $ tar xvfz ctools-00-07-00.tar.gz
  133 +
  134 +(the ``$`` symbol indicates the console prompt and is not part of the
  135 +command that you should type in).
  136 +
  137 +Step in the created directory using
  138 +
  139 +.. code-block:: bash
  140 +
  141 + $ cd ctools-00-07-00
  142 +
  143 +and build the ctools by typing
  144 +
  145 +.. code-block:: bash
  146 +
  147 + $ ./configure
  148 + $ make
  149 +
  150 +at the operating system prompt. The ``./configure`` command customizes
  151 +the Makefiles for the particular system, the ``make`` command compiles
  152 +the source files and builds the executables. Type ``./configure`` and
  153 +not simply ``configure`` to ensure that the configuration script in the
  154 +current directory is run and not some other system-wide configuration script.
  155 +
  156 +You can get the full list of configuration options by typing
  157 +
  158 +.. code-block:: bash
  159 +
  160 + $ ./configure --help
  161 +
  162 +
  163 +Testing ctools
  164 +--------------
  165 +
  166 +Before installing the ctools you should execute the unit test suite to
  167 +make sure that ctools have been built correctly. For this, type
  168 +
  169 +.. code-block:: bash
  170 +
  171 + $ make check
  172 +
  173 +If you have automake version 1.13 or newer installed, you should see the
  174 +following output at the end of the unit testing:
  175 +
  176 +.. code-block:: bash
  177 +
  178 + ============================================================================
  179 + Testsuite summary for ctools 0.7.0
  180 + ============================================================================
  181 + # TOTAL: 3
  182 + # PASS: 3
  183 + # SKIP: 0
  184 + # XFAIL: 0
  185 + # FAIL: 0
  186 + # XPASS: 0
  187 + # ERROR: 0
  188 + ============================================================================
  189 +
  190 +For older automake version, you should see
  191 +
  192 +.. code-block:: bash
  193 +
  194 + ***************
  195 + * Test ctools *
  196 + ***************
  197 + Test ctobssim: .... ok
  198 + Test ctskymap: .. ok
  199 + Test ctbin: .... ok
  200 + Test ctmodel: ...... ok
  201 + Test ctselect: .. ok
  202 + Test ctlike: ........ ok
  203 + PASS: test_ctools.sh
  204 +
  205 + *****************
  206 + * Test cscripts *
  207 + *****************
  208 + Test cspull: .. ok
  209 + Test cstsdist: .. ok
  210 + PASS: test_cscripts.sh
  211 +
  212 + ***********************************
  213 + * ctools Python interface testing *
  214 + ***********************************
  215 + Test executable analysis: ... ok
  216 + Test in-memory analysis: ... ok
  217 + Test diffuse map cube with constant analysis: .... ok
  218 + Test diffuse map cube with power law analysis: ..... ok
  219 + PASS: test_python.py
  220 + ==================
  221 + All 3 tests passed
  222 + ==================
  223 +
  224 +The same detailed information is also available for the newer automake
  225 +versions, but there it is written in log files that you can find in the
  226 +``test`` directory of the ctools:
  227 +
  228 +.. code-block:: bash
  229 +
  230 + test_ctools.sh.log
  231 + test_cscripts.sh.log
  232 + test_python.py.log
  233 +
  234 +If you do not see the same output, but a failure message, please report
  235 +this to the ctools developer team.
  236 +
  237 +
  238 +Installing ctools
  239 +-----------------
  240 +
  241 +The ctools are installed by typing
  242 +
  243 +.. code-block:: bash
  244 +
  245 + $ make install
  246 +
  247 +If the destination directory is owned by ``root`` (which is normally the
  248 +case when using the default), administrator privileges are needed for
  249 +installation. In this case, type
  250 +
  251 +.. code-block:: bash
  252 +
  253 + $ sudo make install
  254 +
  255 +By default, the install directory is set to ``/usr/local/gamma``. To
  256 +change the install directory (for example in case that you do not
  257 +have system administrator privileges), an optional ``--prefix`` argument
  258 +can be given, for example:
  259 +
  260 +.. code-block:: bash
  261 +
  262 + $ ./configure --prefix=$HOME/gamma
  263 +
  264 +
  265 +Setting up the ctools environment
  266 +---------------------------------
  267 +
  268 +If you installed ctools in the same directory as GammaLib (which
  269 +is the default) you are done.
  270 +
  271 +If you decided to install ctools in a different directory, you have to
  272 +configure ctools by setting up some environment variables. This will be
  273 +done automatically by an initialisation script that is found in the ``bin``
  274 +directory of the directory into which ctools has been installed. Assuming
  275 +that you have installed ctools into ``/usr/local/ctools`` you need to add
  276 +the following to your ``$HOME/.bashrc`` or ``$HOME/.profile`` script on a
  277 +Linux machine:
  278 +
  279 +.. code-block:: bash
  280 +
  281 + export CTOOLS=/usr/local/ctools
  282 + source $CTOOLS/bin/ctools-init.sh
  283 +
  284 +If you use C shell or a variant then add the following to your
  285 +``$HOME/.cshrc`` or ``$HOME/.tcshrc`` script:
  286 +
  287 +.. code-block:: csh
  288 +
  289 + setenv CTOOLS /usr/local/ctools
  290 + source $CTOOLS/bin/ctools-init.csh
  291 +
  292 +
  293 +Known problems
  294 +--------------
  295 +
  296 +Python support
  297 +~~~~~~~~~~~~~~
  298 +
  299 +ctools comes with Python wrappers so that all classes can be directly
  300 +used from Python. To compile-in Python support, ctools needs the
  301 +``Python.h`` header file, which on many distributions is not installed
  302 +by default. To make ``Python.h`` available, install the Python developer
  303 +package in your distribution. Otherwise you will not be able to use ctools
  304 +from Python.
  305 +
  306 +Mac OS X
  307 +~~~~~~~~
  308 +
  309 +The Python development package is not installed as default on Mac OS X,
  310 +and consequently, the ``Python.h`` header file is missing that is needed
  311 +to compile in the Python bindings. The configure script recognises this
  312 +fact and adjust the build procedure accordingly, but you will not be able
  313 +to use ctools from Python. So better install the Python development package
  314 +before installing ctools.
  315 +
  316 +It was also reported that adding of
  317 +``export MACOSX_DEPLOYMENT_TARGET=10.6`` to the ``.bashrc`` file was
  318 +necessary one some Mac OS X 10.6 installations to make ctools compile.
  319 +
  320 +Solaris
  321 +~~~~~~~
  322 +
  323 +Although ctools builds on Solaris using the Sun compiler, there are problems
  324 +with global symbols in shared libraries and exception catching, which prevents
  325 +the FITS interface to work correctly. ctools has however been built and tested
  326 +successfully using the GNU compiler, and this is the only build method that
  327 +is currently supported. Problems have also been encountered when compiling
  328 +cfitsio versions more recent than 3.250. The problems have been reported to
  329 +the cfitsio developer team, and are likely to be solved in the future. For
  330 +the time being, it is recommended to use cfitsio version 3.250 on Solaris.
  331 +
  332 +OpenSolaris
  333 +~~~~~~~~~~~
  334 +
  335 +On OpenSolaris, the same problems concerning the SunStudio compiler occur
  336 +as for Solaris, and also here, the GNU compiler is the recommended tool to
  337 +build ctools. Also here, cfitsio version 3.250 is the recommended library as
  338 +more recent version feature relocation problems. ctools has been tested
  339 +using gcc 4.3.2 on OpenSolaris 2009.06. Make sure to create the symbolic
  340 +links
  341 +
  342 +.. code-block:: csh
  343 +
  344 + $ ln -s /usr/bin/gcc4.3.2 /usr/bin/gcc
  345 + $ ln -s /usr/bin/g++4.3.2 /usr/bin/g++
  346 +
  347 +which are not there by default to avoid excess warnings during compilation.
0 348 \ No newline at end of file
... ...