Commit 3c22c3de authored by yoogx's avatar yoogx

* New format for documentation, now using Sphinx

parent ca52a974
# For now, do not build real documentation, it requires LaTeX files
# that may not be installed. However, its source is included in the
# packaging.
DIST_SUBDIRS = real
ADAFILES= $(srcdir)/sources/parse_and_print_aadl.adb
AADLFILES= $(srcdir)/sources/scenario_ada.aadl \
$(srcdir)/sources/scenario_c.aadl \
$(srcdir)/sources/scenario_common.aadl \
$(srcdir)/sources/example_pn.aadl \
$(top_srcdir)/resources/AADLv1/aadl_project.aadl \
$(top_srcdir)/resources/AADLv1/aadl_properties.aadl \
$(top_srcdir)/resources/deployment.aadl \
$(top_srcdir)/resources/ocarina_config.aadl
APIFILES= \
$(top_srcdir)/src/core/tree/ocarina-me_aadl-aadl_tree-entities.ads \
$(top_srcdir)/src/core/tree/ocarina-me_aadl-aadl_tree-entities-properties.ads \
$(top_srcdir)/src/core/model/ocarina-builder.ads \
$(top_srcdir)/src/core/model/ocarina-builder-aadl.ads \
$(top_srcdir)/src/core/model/ocarina-builder-aadl-annexes.ads \
$(top_srcdir)/src/core/model/ocarina-builder-aadl-components.ads \
$(top_srcdir)/src/core/model/ocarina-builder-aadl-components-connections.ads \
$(top_srcdir)/src/core/model/ocarina-builder-aadl-components-features.ads \
$(top_srcdir)/src/core/model/ocarina-builder-aadl-components-flows.ads \
$(top_srcdir)/src/core/model/ocarina-builder-aadl-components-modes.ads \
$(top_srcdir)/src/core/model/ocarina-builder-aadl-components-subcomponents.ads\
$(top_srcdir)/src/core/model/ocarina-builder-aadl-components-subprogram_calls.ads \
$(top_srcdir)/src/core/model/ocarina-builder-aadl-namespaces.ads \
$(top_srcdir)/src/core/model/ocarina-builder-aadl-properties.ads \
$(top_srcdir)/src/core/model/ocarina-analyzer-aadl-finder.ads \
$(top_srcdir)/src/core/model/ocarina-analyzer-aadl-queries.ads
GEN_TEXIFILES= ${notdir $(ADAFILES:=.texi) $(AADLFILES:=.texi) $(APIFILES:=.texi)}
IMAGE_NAMES=\
$(srcdir)/images/component\
$(srcdir)/images/connection\
$(srcdir)/images/feature\
$(srcdir)/images/mubroker_complet\
$(srcdir)/images/spg_connection\
$(srcdir)/images/subprogram
ALL_IMAGES= $(IMAGE_NAMES:=.eps) $(IMAGE_NAMES:=.png) $(IMAGE_NAMES:=.pdf)
KW_FILES = \
$(srcdir)/aadl.kw\
$(srcdir)/ada.kw
SED_FILES = ${notdir $(KW_FILES:.kw=.sed)}
GUIDE=ocarina GUIDE=ocarina
GUIDE_TEXIFILES =\
$(srcdir)/$(GUIDE).texi\
$(GEN_TEXIFILES) \
gfdl.texi
info_TEXINFOS = ocarina.texi
ocarina_TEXINFOS=$(GUIDE_TEXIFILES)
man_MANS = ocarina-config.1 ocarina.1 man_MANS = ocarina-config.1 ocarina.1
GUIDE_RSTFILES = $(srcdir)/about.rst $(srcdir)/gfdl.rst \
$(srcdir)/introduction.rst $(srcdir)/annexes.rst index.rst \
$(srcdir)/python.rst $(srcdir)/editors.rst \
$(srcdir)/installation.rst $(srcdir)/usage.rst
EXTRA_DIST= $(srcdir)/CODING_GUIDELINES $(srcdir)/CONTRIBUTING \ EXTRA_DIST= $(srcdir)/CODING_GUIDELINES $(srcdir)/CONTRIBUTING \
$(srcdir)/PROBLEM-REPORT-FORM $(GUIDE_TEXIFILES) $(ALL_IMAGES) \ $(srcdir)/PROBLEM-REPORT-FORM $(GUIDE_TEXIFILES) $(ALL_IMAGES) \
$(ADAFILES) $(AADLFILES) $(KW_FILES) $(srcdir)/ocarina.css \
$(man_MANS) $(srcdir)/ocarina-config.html \ $(man_MANS) $(srcdir)/ocarina-config.html \
$(srcdir)/ocarina_man.html $(srcdir)/ocarina_man.html
all-local: $(GUIDE).html $(GUIDE).pdf all-local: $(GUIDE).html $(GUIDE).pdf
$(GUIDE).html: $(IMAGES) $(GUIDE_TEXIFILES) $(GUIDE).html: $(GUIDE_RSTFILES)
-$(MAKEINFO) --css-include=$(srcdir)/ocarina.css --force --html --ifhtml --number-sections $(srcdir)/$(GUIDE).texi -o $(GUIDE).html make html
rm -rf $(GUIDE).html/images
mkdir -p $(GUIDE).html/images
cp -p $(srcdir)/images/*.png $(GUIDE).html/images/
INDEX_FILE="$(GUIDE).html/index.html";\
TMP_FILE="$$INDEX_FILE.tmp"; \
cat "$$INDEX_FILE" | sed 's/$$LastChangedDate: \([^$$]*\) \$$/Last Modified: \1/g' > "$$TMP_FILE"; \
mv -f "$$TMP_FILE" "$$INDEX_FILE"
$(GUIDE).pdf: $(IMAGES) $(GUIDE_TEXIFILES) $(GUIDE).pdf: $(IMAGES) $(GUIDE_RSTFILES)
-$(TEXI2PDF) $(srcdir)/$(GUIDE).texi make latexpdf
clean-local: clean-local:
rm -f *.aux *.log *.dvi *.info *.tmp rm -f *~
rm -f *.cp *.pg *.toc *.vr *.fn *.ky *.tp *~ -rm -rf $(BUILDDIR)/*
distclean-local: distclean-local:
rm -f $(GEN_TEXIFILES) rm -f $(GEN_TEXIFILES)
...@@ -112,71 +49,52 @@ dist-hook: all ...@@ -112,71 +49,52 @@ dist-hook: all
install-data-local: all install-data-local: all
$(INSTALL) -d $(DESTDIR)$(datadir)/doc/ocarina $(INSTALL) -d $(DESTDIR)$(datadir)/doc/ocarina
if [ -r $(GUIDE).pdf ]; then \ if [ -r $(builddir)/_build/latex/$(GUIDE).pdf ]; then \
$(INSTALL_DATA) $(GUIDE).pdf $(DESTDIR)$(datadir)/doc/ocarina; \ $(INSTALL_DATA) $(builddir)/_build/latex/$(GUIDE).pdf $(DESTDIR)$(datadir)/doc/ocarina; \
$(INSTALL) -d $(DESTDIR)$(datadir)/doc/ocarina/$(GUIDE).html; \ $(INSTALL) -d $(DESTDIR)$(datadir)/doc/ocarina/$(GUIDE).html; \
for f in $(GUIDE).html/*.html; do \ $(CP) -r $(builddir)/_build/html/* $(DESTDIR)$(datadir)/doc/ocarina/$(GUIDE).html; \
$(INSTALL_DATA) $$f $(DESTDIR)$(datadir)/doc/ocarina/$(GUIDE).html; \
done; \
$(INSTALL) -d $(DESTDIR)$(datadir)/doc/ocarina/$(GUIDE).html/images; \
for f in $(GUIDE).html/images/*.png; do \
$(INSTALL_DATA) $$f $(DESTDIR)$(datadir)/doc/ocarina/$(GUIDE).html/images; \
done; \
else \
$(INSTALL_DATA) $(srcdir)/$(GUIDE).pdf $(DESTDIR)$(datadir)/doc/ocarina; \
$(INSTALL) -d $(DESTDIR)$(datadir)/doc/ocarina/$(GUIDE).html; \
for f in $(srcdir)/$(GUIDE).html/*.html; do \
$(INSTALL_DATA) $$f $(DESTDIR)$(datadir)/doc/ocarina/$(GUIDE).html; \
done; \
$(INSTALL) -d $(DESTDIR)$(datadir)/doc/ocarina/$(GUIDE).html/images; \
for f in $(srcdir)/$(GUIDE).html/images/*.png; do \
$(INSTALL_DATA) $$f $(DESTDIR)$(datadir)/doc/ocarina/$(GUIDE).html/images; \
done; \
fi fi
$(INSTALL_DATA) $(srcdir)/CONTRIBUTING $(DESTDIR)$(datadir)/doc/ocarina $(INSTALL_DATA) $(srcdir)/CONTRIBUTING $(DESTDIR)$(datadir)/doc/ocarina
$(INSTALL_DATA) $(srcdir)/PROBLEM-REPORT-FORM $(DESTDIR)$(datadir)/doc/ocarina $(INSTALL_DATA) $(srcdir)/PROBLEM-REPORT-FORM $(DESTDIR)$(datadir)/doc/ocarina
$(INSTALL_DATA) $(builddir)/ocarina-config.html $(DESTDIR)$(datadir)/doc/ocarina $(INSTALL_DATA) $(srcdir)/ocarina-config.html $(DESTDIR)$(datadir)/doc/ocarina
$(INSTALL_DATA) $(builddir)/ocarina_man.html $(DESTDIR)$(datadir)/doc/ocarina $(INSTALL_DATA) $(srcdir)/ocarina_man.html $(DESTDIR)$(datadir)/doc/ocarina
$(INSTALL_DATA) $(srcdir)/ocarina.css $(DESTDIR)$(datadir)/doc/ocarina $(INSTALL_DATA) $(srcdir)/ocarina.css $(DESTDIR)$(datadir)/doc/ocarina
uninstall-local: uninstall-local:
rm -rf $(DESTDIR)$(datadir)/doc/ocarina rm -rf $(DESTDIR)$(datadir)/doc/ocarina
$(GUIDE_TEXIFILES): ada-stamp adb-stamp ads-stamp aadl-stamp
ada-stamp: $(top_srcdir)/tools/gentexifile $(ADAFILES) sed-stamp
for f in ${filter %.ada, $(ADAFILES)}; do \
$(SHELL) $(top_srcdir)/tools/gentexifile $$f; \
done
touch ada-stamp
adb-stamp: $(top_srcdir)/tools/gentexifile $(ADAFILES) sed-stamp
for f in ${filter %.adb, $(ADAFILES)}; do \
$(SHELL) $(top_srcdir)/tools/gentexifile $$f; \
done
touch adb-stamp
ads-stamp: $(top_srcdir)/tools/gen_api_doc $(APIFILES)
ABS_TOP_SRCDIR="@abs_top_srcdir@" \
ABS_TOP_BUILDDIR="@abs_top_builddir@" \
$(SHELL) $(top_srcdir)/tools/gen_api_doc
touch ads-stamp
aadl-stamp: $(top_srcdir)/tools/gentexifile $(AADLFILES) sed-stamp
for f in $(AADLFILES); do \
$(SHELL) $(top_srcdir)/tools/gentexifile $$f; \
done
touch aadl-stamp
sed-stamp: $(top_srcdir)/tools/gensedfile $(KW_FILES)
for f in $(KW_FILES); do \
$(SHELL) $(top_srcdir)/tools/gensedfile $$f; \
done
touch sed-stamp
############################################################################### ###############################################################################
# Building manpages # SPHINX rules
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = $(builddir)/_build
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -c $(srcdir) -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(srcdir)
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
###############################################################################
# Building manpages
build_man: $(top_srcdir)/ocarina-config.in build_man: $(top_srcdir)/ocarina-config.in
chmod 755 $(top_builddir)/ocarina-config chmod 755 $(top_builddir)/ocarina-config
......
aadlboolean
aadlinteger
aadlreal
aadlstring
access
all
and
annex
applies
binding
bus
calls
classifier
connections
constant
data
delta
device
end
enumeration
event
extends
false
features
flow
flows
group
implementation
in
inherit
initial
inverse
is
list
memory
mode
modes
none
not
of
or
out
package
parameter
path
port
private
process
processor
properties
property
provides
public
range
reference
refined
refines
requires
server
set
sink
source
subcomponents
subprogram
system
thread
to
true
type
units
value
.. _about:
================
About This Guide
================
About this Guide
################
This guide describes the use of Ocarina, a compiler for the AADL.
It presents the features of the compiler, related APIs and tools; and
details how to use them to build and exploit AADL models.
It also details model transformations of AADL models onto Petri Net models
Companion documents describe other add-ons for Ocarina:
* PolyORB-HI/Ada, a High-Integrity AADL runtime and its code generator
built on top of Ocarina that targets Ada targets: Native or bare
board runtimes;
* PolyORB-HI/C, a High-Integrity AADL runtime and its code generator
built on top of Ocarina that targets C targets: POSIX and RT-POSIX
systems, RTEMS.
Document Conventions
####################
This document uses the following conventions:
.. note:: This is just a note, for your information.
.. warning:: This is a warning, something you should take care of.
A filename or a path to a filename is displayed like this:
:file:`/path/to/filename.ext`
A command to type in the shell is displayed like this:
:command:`command --arguments`
A sample of code is illustrated like this:
::
First Line of Code
Second Line of Code
...
.. _copyright:
Copyright Information
#####################
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation
License, Version 1.1 or any later version published by the
Free Software Foundation; with no Invariant Sections, no
Front-Cover Texts, and with no Back-Cover Texts. A copy of
the license is included in :ref:`gfdl`.
If you have any questions regarding this document, its
copyright, or publishing this document in non-electronic form,
please contact us.
with
while
when
use
until
type
then
terminate
task
tagged
subtype
separate
select
reverse
reverse
return
requeue
renames
rem
record
range
raise
protected
procedure
private
pragma
package
out
others
or
of
null
not
new
mod
loop
limited
is
in
if
goto
generic
function
for
exit
exception
entry
end
elsif
else
do
digits
delta
delay
declare
constant
configuration
case
body
begin
array
and
all
aliased
access
accept
abstract
abs
abort
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
This diff is collapsed.
.. _editors:
==============
Editor support
==============
The AADL modes for Emacs and vim provide syntax coloration and
automatic indentation features when editing AADL files.
Emacs
=====
To load the AADL mode for Emacs, you need to add the following line to
your emacs configuration file (usually located in :file:`~/.emacs`) ::
(load "/path/to/this/file.el")
For more details on this mode, please refer to the emacs contextual help.
.. figure:: aadl-mode.png
:align: center
AADL mode for Emacs
vim
===
The AADL mode for vim is made of two files aadl.vim: one for syntactic
coloration, and the other for indentation. The file for indentation
must be placed into ~/.vim/indent/ while the one for syntactic
coloration must be placed into :file:`~/.vim/syntax/`
To load the AADL mode whenever you edit AADL files, create a file
named :file:`~/.vim/filetype.vim`, in which you write::
augroup filetypedetect
au BufNewFile,BufRead *.aadl setf aadl
augroup END
For more details, please read the documentation of vim.
.. figure:: aadl-mode_vim.png
:align: center
AADL mode for vim
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This source diff could not be displayed because it is too large. You can view the blob instead.
This diff is collapsed.
This diff is collapsed.
.. Ocarina documentation master file, created by
sphinx-quickstart on Mon Mar 3 22:24:45 2014.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Ocarina User's Guide
====================
.. toctree::
:maxdepth: 2
about
introduction
installation
usage
osate-ocarina
python
editors
gfdl
annexes
.. _installation:
============
Installation
============
Supported platforms
###################
Ocarina has been compiled and successfully tested on the following platforms:
* GNU/Linux
* Mac OS X
* Windows
.. note:: Ocarina should compile and run on every target for which GNAT is available.
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.
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
Build instructions
##################
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
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,
automake 1.6.3 or newer.
\ No newline at end of file
.. _introduction:
============
Introduction
============
About Ocarina
#############
.. index:: Ocarina (introduction)
Ocarina is an application that can be used to analyze and build
applications from AADL descriptions. Because of its modular
architecture, Ocarina can also be used to add AADL functions to
existing applications. Ocarina supports the AADL 1.0 and AADLv2
standards and proposes the following features :
* Parsing and pretty printing of AADL models
* Semantics checks
* Code generation, with the following code generators
* PolyORB-HI/Ada, a High-Integrity AADL runtime and its code
generator built on top of Ocarina that targets Ada targets: Native
or bare board runtimes;
* PolyORB-HI/C, a High-Integrity AADL runtime and its code generator