installation.rst 6.13 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

.. _installation:

============
Installation
============

Supported platforms
###################

Ocarina has been compiled and successfully tested on the following platforms:

* GNU/Linux
* Mac OS X
* Windows

17 18
.. note:: Ocarina should compile and run on every target for which
          GNAT is available.
19 20 21 22 23 24 25 26 27 28 29 30 31 32 33

Build requirements
##################

An Ada compiler:

* GNAT Pro, GNAT GPL or FSF/GCC with Ada back-end

.. note:: per construction, the macro configure used to find your GNAT
   compiler looks first to the executable gnatgcc, then adagcc and
   finally to gcc to find out which Ada compiler to use. You should be
   very careful with your path and binaries if you have multiple GNAT
   versions installed. See below explanations on the ADA environment
   variable if you need to override the default guess.

34
.. note:: Ocarina requires at least GCC/FSF 5.2 or GNAT GPL 2015.
35

36 37
* autoconf, automake, GNU Make, python

38 39 40 41 42 43 44 45 46 47
Optional components:

* GNATColl for the Ocarina Python bindings
* Sphinx and the sphinx-bootstrap-theme to build the documentation,
  and a full valid LaTeX installation
* Bound-T for the WCET analysis (:code:`bound_t` backend)
* Cheddar for scheduling analysis (:code:`cheddar` backend)
* MAST for scheduling analysis (:code:`mast` backend)
* RTOS supported by one of the Ocarina runtimes

48 49 50
Semi-automated build instructions
#################################

yoogx's avatar
yoogx committed
51
The `ocarina-build https://github.com/OpenAADL/ocarina-build/`_
52 53 54 55 56 57 58 59 60 61 62
repository proposes a script, `build_ocarina.sh`, to get source code,
compile and test Ocarina.

It relies on bash constructs to coordinate various activities to:

- fetch Ocarina source, with its runtimes PolyORB-HI/Ada and
  PolyORB-HI/C
- compile Ocarina, and install it in a local directory
- run Ocarina testsuites, and eventually collect coverage metrics

To install this script, simply clone the repository and run the
yoogx's avatar
yoogx committed
63
script. Use `build_ocarina.sh -h` to access its help.
64 65

* The following command gets a fresh copy of Ocarina source code:
yoogx's avatar
yoogx committed
66
  `./build_ocarina.sh -s -u`
67 68

* The following command compiles and installs Ocarina:
yoogx's avatar
yoogx committed
69
  `./build_ocarina.sh -b`
70 71 72

Manual build instructions
#########################
73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91

To compile and install Ocarina, execute in a shell::

       % ./configure [some options]
       % make              (or gmake if your make is not GNU make)
       % make install      (ditto)

This will install files in standard locations. If you want to choose
another prefix than `/usr/local`, give configure use `--prefix` argument

.. note:: you MUST use GNU make to compile this software.

.. note:: If you modify source files, build Ocarina after a checkout
   or make distclean, or the directory hierarchy of the source files,
   you should re-generate autoconf and automake files (configure,
   Makefile.in...); to do this, from the main directory, run::

   ./support/reconfig

92
.. note:: To install the PolyORB/HI runtimes, you may use the script
yoogx's avatar
yoogx committed
93 94
   get_runtimes.sh. It will install required ressources in the
   Ocarina source tree::
95 96 97

   ./support/get_runtimes.sh po_hi_ada po_hi_c

98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161
Build options
#############

Available options for the configure script include:

* `--enable-doc`: to build the documentation

.. note:: You must first install Sphinx and the sphinx-bootstrap-theme

* `--enable-shared`: to build shared libraries

* `--enable-debug`: enable debugging information generation and
  supplementary runtime checks. Note that this option has a
  significant space and time cost, and is not recommended for
  production use.

* `--enable-python`: to build the Python bindings.

.. note:: This option requires GNATColl to be installed, and Ocarina
  built with shared libraries support.

* `--with-ocarina-runtimes=x`: enable building Ocarina along with the
  requested runtimes. x is a set of valid runtimes located in the
  resources/runtimes directory. x is case insensitive. Examples of
  use:

* `--with-ocarina-runtimes=all`: compile Ocarina along with all the
  runtimes. All the Ocarina runtimes MUST be located in the
  resources/runtimes directory.

* `--with-ocarina-runtimes="polyorb-hi-c PolyORB-HI-Ada"`: compile
  Ocarina along with the PolyORB-HI-Ada and the PolyORB-HI-C
  runtimes.

.. note:: The runtime directories (e.g. :file:`polyorb-hi-ada` or
  :file:`polyorb-hi-c` MUST exist in the resources/runtimes directory.

No option: compile Ocarina along with all the runtimes found in the
resources/runtimes directory.

For more details on available options, one may use the `--help` flag.

The following environment variables can be used to override
configure's guess at what compilers to use:

* `CC`: the C compiler
* `ADA`: the Ada 95 compiler (e.g. gcc, gnatgcc or adagcc)

For example, if you have two versions of GNAT installed and available
in your PATH, and configure picks the wrong one, you can indicate what
compiler should be used with the following syntax::

       % ADA=/path/to/good/compiler/gcc ./configure [options]

Ocarina will be compiled with GNAT build host's configuration,
including run-time library. You may override this setting using
`ADA_INCLUDE_PATH` and `ADA_OBJECTS_PATH` environment variables. See GNAT
User's Guide for more details.

.. note:: Developers building Ocarina from the version control
   repository who need to rebuild the configure and Makefile.in files
   should use the script support/reconfig for this purpose. This
   should be done after each update from the repository. In addition
   to the requirements above, they will need autoconf 2.57 or newer,
162
   automake 1.6.3 or newer.
163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184

Windows-specific options
########################

Ocarina relies on autotools script to compile, and then on Python for
testing and running regression testing. Such setting is unusual for
Windows and requires additional tools.

The recommended set of tools for compiling Ocarina under Windows
(tested on Windows 7) is to

* install Cygwin, and use its terminal for running all compilation scripts

* install autoconf, automake and GNU Make

* install native gcc, this compiler is used for compiling `mknodes`

* install `x86_64-w64-mingw32` gcc tool-chain, this compiler is used
  to "cross-compile" from cygwin to regular Windows.

.. note:: It is highly recommended to rely on the `build_ocarina.sh`
   script for the Windows platform.