1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/tools/make_docs.sh Thu Apr 23 00:03:59 2020 +0200
1.3 @@ -0,0 +1,34 @@
1.4 +#!/bin/sh
1.5 +
1.6 +THISDIR=`dirname "$0"`
1.7 +INDIR="$THISDIR/../wiki"
1.8 +OUTDIR="$THISDIR/../html"
1.9 +
1.10 +ROOT="idl4re"
1.11 +
1.12 +MAPPING='
1.13 +--mapping WikiPedia https://en.wikipedia.org/wiki/
1.14 +--mapping MoinMoin https://moinmo.in/
1.15 +'
1.16 +
1.17 +THEME='--theme mercurial'
1.18 +
1.19 +if [ "$1" = '--web' ] ; then
1.20 + DOCINDEX=
1.21 + shift 1
1.22 +else
1.23 + DOCINDEX='--document-index index.html'
1.24 +fi
1.25 +
1.26 +FILENAMES=${*:-'--all'}
1.27 +
1.28 +moinconvert --input-dir "$INDIR" \
1.29 + --input-page-sep '--' \
1.30 + --output-dir "$OUTDIR" \
1.31 + --root "$ROOT" \
1.32 + --format html \
1.33 + --macros \
1.34 + $DOCINDEX \
1.35 + $MAPPING \
1.36 + $THEME \
1.37 + $FILENAMES
2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2 +++ b/docs/tools/make_releases.sh Thu Apr 23 00:03:59 2020 +0200
2.3 @@ -0,0 +1,39 @@
2.4 +#!/bin/sh
2.5 +
2.6 +DIRNAME=`dirname "$0"`
2.7 +PROGNAME=`basename "$0"`
2.8 +
2.9 +ARCHIVE=idl4re
2.10 +
2.11 +if [ ! "$1" ] || [ "$1" = '--help' ] ; then
2.12 + cat 1>&2 <<EOF
2.13 +Usage: $PROGNAME <output directory> [ -f ]
2.14 +
2.15 +Make release archives from tags starting with "rel-" in the repository,
2.16 +storing the archives in the output directory. If an archive already exists for
2.17 +a release, it is not regenerated unless the -f (force) option is given.
2.18 +
2.19 +All newly-created archive filenames are emitted on standard output.
2.20 +EOF
2.21 + exit 1
2.22 +fi
2.23 +
2.24 +OUTDIR=$1
2.25 +FORCE=$2
2.26 +
2.27 +if [ "$FORCE" != '-f' ]; then
2.28 + FORCE=
2.29 +fi
2.30 +
2.31 +if [ ! -e "$OUTDIR" ]; then
2.32 + mkdir -p "$OUTDIR"
2.33 +fi
2.34 +
2.35 +for TAG in `hg tags | grep ^rel- | cut -f 1 -d ' '` ; do
2.36 + NUM=`echo "$TAG" | sed 's/rel-//;s/-/./g'`
2.37 + OUTFILE="$OUTDIR/$ARCHIVE-$NUM.tar.bz2"
2.38 + if [ ! -e "$OUTFILE" ] || [ "$FORCE" ]; then
2.39 + hg archive -t tbz2 -r "$TAG" "$OUTFILE"
2.40 + echo "$OUTFILE"
2.41 + fi
2.42 +done
3.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
3.2 +++ b/docs/tools/sign_releases.sh Thu Apr 23 00:03:59 2020 +0200
3.3 @@ -0,0 +1,39 @@
3.4 +#!/bin/sh
3.5 +
3.6 +DIRNAME=`dirname "$0"`
3.7 +PROGNAME=`basename "$0"`
3.8 +
3.9 +if [ ! "$1" ] || [ "$1" = '--help' ] ; then
3.10 + cat 1>&2 <<EOF
3.11 +Usage: $PROGNAME <archive directory> [ -f ]
3.12 +
3.13 +Sign archives in the given archive directory, invoking GPG to produce a
3.14 +detached signature. If a signature already exists for an archive, it is not
3.15 +regenerated unless the -f (force) option is given.
3.16 +
3.17 +All newly-created signature filenames are emitted on standard output.
3.18 +EOF
3.19 + exit 1
3.20 +fi
3.21 +
3.22 +OUTDIR=$1
3.23 +FORCE=$2
3.24 +
3.25 +if [ "$FORCE" != '-f' ]; then
3.26 + FORCE=
3.27 +fi
3.28 +
3.29 +if [ ! -e "$OUTDIR" ]; then
3.30 + cat 1>&2 <<EOF
3.31 +No archive directory to process.
3.32 +EOF
3.33 + exit 1
3.34 +fi
3.35 +
3.36 +for FILENAME in "$OUTDIR/"*".tar.bz2" ; do
3.37 + OUTFILE="$FILENAME.asc"
3.38 + if [ ! -e "$OUTFILE" ] || [ "$FORCE" ]; then
3.39 + gpg --sign -a -b "$FILENAME"
3.40 + echo "$OUTFILE"
3.41 + fi
3.42 +done
4.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
4.2 +++ b/docs/wiki/Development Thu Apr 23 00:03:59 2020 +0200
4.3 @@ -0,0 +1,431 @@
4.4 += Development =
4.5 +
4.6 +The current implementation of the [[idl|`idl`]] tool employs the stated
4.7 +[[Prerequisites|prerequisites]] with the software written in the C programming
4.8 +language. A Flex-based lexical analyser produces tokens that are consumed by a
4.9 +Bison-based parser generator whose rules call program functions to build
4.10 +structures and generate output.
4.11 +
4.12 +<<TableOfContents(2)>>
4.13 +
4.14 +== Main Program ==
4.15 +
4.16 +The `main.c` file contains the `main` function whose responsibilities include
4.17 +the following:
4.18 +
4.19 + * Processing program arguments and options using C library `getopt`
4.20 + functionality, configuring the program behaviour and output.
4.21 +
4.22 + * Input file access and output coordination.
4.23 +
4.24 + * Parser initialisation and invocation using the `yyrestart` and
4.25 + `yyparse` functions, and parser state management.
4.26 +
4.27 +Various helper functions are also defined.
4.28 +
4.29 +== Configuration ==
4.30 +
4.31 +The `config.c` and `config.h` files define configuration state for the program
4.32 +as it processes input files, with the latter defining the nature of the state
4.33 +and the former recording the actual state set by the main program when
4.34 +interpreting program arguments and options. Thus, this configuration can be
4.35 +considered to be a concise, validated form of those arguments and options.
4.36 +
4.37 +== Lexical Analysis ==
4.38 +
4.39 +The `idl.lex` file defines a scanner or lexical analyser for the language used
4.40 +to describe interfaces. For the most part, it merely matches sequences of
4.41 +characters and produces token identifiers, with no additional information
4.42 +being provided for tokens having a fixed form (typically keywords and
4.43 +symbols).
4.44 +
4.45 +Tokens with varying input forms (identifiers, numbers, and so on) also have a
4.46 +value associated with them indicating such things as the precise sequence of
4.47 +matching characters or the numeric equivalent of those characters. Such
4.48 +details are stored using members of the value type, referenced via the
4.49 +``yylval`` variable. The token value type is itself defined in the parser
4.50 +definition.
4.51 +
4.52 +=== Operating Modes ===
4.53 +
4.54 +There are two distinct operating modes of the scanner:
4.55 +
4.56 + * The default mode recognising most elements of the language.
4.57 + * A comment mode consuming the text found within comment delimiters.
4.58 +
4.59 +When a comment start indicator (`/*`) is encountered in the default mode, the
4.60 +mode is switched to the comment mode and all input is consumed until the
4.61 +comment end indicator (`*/`) is encountered, at which point the default mode
4.62 +is selected again.
4.63 +
4.64 +A special indicator is used to declare the comment mode in the scanner file:
4.65 +
4.66 +{{{
4.67 +%x comment
4.68 +}}}
4.69 +
4.70 +All rules applicable in this mode are prefixed with `<comment>` in the file to
4.71 +distinguish them from rules applicable in the default mode.
4.72 +
4.73 +== Parsing ==
4.74 +
4.75 +The `idl.y` file defines a parser for the interface description language. It
4.76 +starts by attempting to satisfy the `file` rule, matching statements until the
4.77 +end of input, invoking the `write_files` function to generate the configured
4.78 +output from the tool.
4.79 +
4.80 +As each rule is evaluated, tokens are consumed from the scanner and operations
4.81 +are performed to build up a structure describing the input. Where a rule
4.82 +cannot be evaluated successfully, the included ``yyerror`` function emits a
4.83 +message and the parsing will halt.
4.84 +
4.85 +(Error handling and reporting could do to be improved.)
4.86 +
4.87 +=== Token and Rule Result Values ===
4.88 +
4.89 +For interoperability with the scanner or lexical analyser, the parser defines
4.90 +the nature of the values associated with tokens using the `%union`
4.91 +declaration, these including a `str` (string) interpretation and a `num`
4.92 +(numeric) interpretation of a value.
4.93 +
4.94 +Since token values are propagated between parser rules, the `%union`
4.95 +declaration is augmented with other interpretations that are employed by the
4.96 +rules. Consequently, rules can obtain values for tokens that were produced by
4.97 +the scanner (such as numbers and strings) but then incorporate them into other
4.98 +kinds of values or structures, passing them on to other rules. These other
4.99 +rules can treat such propagated values in the same way as those produced
4.100 +directly by the scanner.
4.101 +
4.102 +For example, the `include` rule obtains a value associated with a header
4.103 +filename. This filename is associated with the `HEADER` token and its value is
4.104 +interpreted as a string. However, the rule needs to prepare a structure that
4.105 +incorporates the filename and that can be referenced by other structures. To
4.106 +achieve this, a `%union` member is defined for the structure type concerned:
4.107 +
4.108 +{{{
4.109 +%union {
4.110 + long num;
4.111 + char *str;
4.112 + struct include inc;
4.113 + ...
4.114 +}
4.115 +}}}
4.116 +
4.117 +The member name, `inc`, is then associated with the `include` rule:
4.118 +
4.119 +{{{
4.120 +%type <inc> include
4.121 +}}}
4.122 +
4.123 +With this, the rule can be considered to be working to populate a value of the
4.124 +indicated type (`struct include`), and where other rules reference the result
4.125 +of the rule, they will be able to recognise the type of this result.
4.126 +
4.127 +=== Value Copying ===
4.128 +
4.129 +When rules obtain values to store them, it is necessary to copy the obtained
4.130 +values because these values may not be allocated in any permanent sense: they
4.131 +may only be available at a particular point during the scanning of input, and
4.132 +any attempt to reference them later may yield an invalid value. Consequently,
4.133 +a `copy` function and a suite of convenience macros (defined in `parser.h`)
4.134 +allocate memory for new values.
4.135 +
4.136 +(Currently, the management of allocated memory is deficient in that such
4.137 +memory is not deallocated. However, since the program is intended to have a
4.138 +limited running time and handle limited numbers of input files, no effort has
4.139 +been directed towards tidying up this allocated memory.)
4.140 +
4.141 +=== Rules and Structures ===
4.142 +
4.143 +Generally, the structures built using the result values reflect the structure
4.144 +of the rules describing the interface description language. However, the form
4.145 +of rules, necessary as it is for parsing, is not entirely optimal for a
4.146 +generated structure. Consider the following rule:
4.147 +
4.148 +{{{
4.149 +attributes : attribute SEP attributes
4.150 + | attribute
4.151 + ;
4.152 +}}}
4.153 +
4.154 +Consider a pair of attributes:
4.155 +
4.156 +{{{
4.157 +first,second
4.158 +}}}
4.159 +
4.160 +With the `attribute` rule matching each identifier, and with the `attributes`
4.161 +rule incorporating a single attribute value within a structure referencing
4.162 +other attribute, the following structure would emerge:
4.163 +
4.164 +######## A graph showing a generated structure derived from rules...
4.165 +
4.166 +{{{#!graphviz
4.167 +#format svg
4.168 +#transform notugly
4.169 +digraph rule_structure
4.170 +{
4.171 + graph [fontsize="15.0",fontname="Helvetica"];
4.172 + node [shape=record,fontname="Helvetica"];
4.173 +
4.174 + attributes1 [label="{attributes | {<f> attribute |<a> attributes}}"];
4.175 + first [label="{attribute | { \"first\" | ... }}"];
4.176 + attributes2 [label="{attributes | {<f> attribute |<a> attributes}}"];
4.177 + second [label="{attribute | { \"second\" | ... }}"];
4.178 +
4.179 + attributes1:f -> first;
4.180 + attributes1:a -> attributes2;
4.181 + attributes2:f -> second;
4.182 +}
4.183 +}}}
4.184 +
4.185 +######## End of graph.
4.186 +
4.187 +A more natural structure would instead employ a linked list of attributes:
4.188 +
4.189 +######## A graph showing a generated structure employing lists...
4.190 +
4.191 +{{{#!graphviz
4.192 +#format svg
4.193 +#transform notugly
4.194 +digraph natural_structure
4.195 +{
4.196 + graph [fontsize="15.0",fontname="Helvetica"];
4.197 + node [shape=record,fontname="Helvetica"];
4.198 +
4.199 + first [label="{attribute | { \"first\" | ... |<a> tail }}"];
4.200 + second [label="{attribute | { \"second\" | ... |<a> tail }}"];
4.201 +
4.202 + first:a -> second;
4.203 +}
4.204 +}}}
4.205 +
4.206 +To achieve this, a tail member is defined in structures, and instead of
4.207 +wrapping results in new structures at each level of the rule hierarchy,
4.208 +results are effectively combined by having one result reference another via
4.209 +the tail member, thus linking together collections of results.
4.210 +
4.211 +######## End of graph.
4.212 +
4.213 +== Interface Structure ==
4.214 +
4.215 +The `types.h` file defines the structural elements of interfaces prepared
4.216 +during the processing of the input files. A hierarchy of structure types is
4.217 +defined as follows:
4.218 +
4.219 +######## A graph showing the relationship between structure types...
4.220 +
4.221 +{{{#!graphviz
4.222 +#format svg
4.223 +#transform notugly
4.224 +digraph types
4.225 +{
4.226 + graph [fontsize="15.0",fontname="Helvetica"];
4.227 + node [shape=record,fontname="Helvetica"];
4.228 +
4.229 + interface [label="{interface | {name |<s> signatures |<a> attributes |<i> includes |<t> tail}}"];
4.230 + signature [label="{signature | {qualifier | operation |<p> parameters |<a> attributes |<t> tail}}"];
4.231 + attribute [label="{attribute | {attribute |<i> identifiers |<t> tail}}"];
4.232 + parameter [label="{parameter | {specifier | class |<i> identifiers |<t> tail}}"];
4.233 + identifier [label="{identifier | {identifier |<t> tail}}"];
4.234 + include [label="{include | {filename |<t> tail}}"];
4.235 +
4.236 + interface:s -> signature;
4.237 + interface:a -> attribute;
4.238 + interface:i -> include;
4.239 + interface:t -> interface;
4.240 +
4.241 + signature:p -> parameter;
4.242 + signature:a -> attribute;
4.243 + signature:t -> signature;
4.244 +
4.245 + attribute:i -> identifier;
4.246 + attribute:t -> attribute;
4.247 +
4.248 + parameter:i -> identifier;
4.249 + parameter:t -> parameter;
4.250 +
4.251 + identifier:t -> identifier;
4.252 +
4.253 + include:t -> include;
4.254 +}
4.255 +}}}
4.256 +
4.257 +######## End of graph.
4.258 +
4.259 +The nature of the hierarchy should reflect the conceptual form of the input.
4.260 +It should be noted that header file information (represented by `include`
4.261 +structures) is associated with interface information (represented by
4.262 +`interface` structures). This arrangement merely attempts to indicate the
4.263 +header file declarations that preceded specific interface declarations, but
4.264 +the two different types of information should arguably be grouped within a
4.265 +file-oriented structure.
4.266 +
4.267 +== Code Generation ==
4.268 +
4.269 +The `program.c` and `program.h` files define the functions that coordinate the
4.270 +generation of program code. It is in `program.c` that files are opened for
4.271 +writing (using the `get_output_file` function provided by `common.c`), and two
4.272 +principal functions are involved in initiating the population of these files:
4.273 +
4.274 + * `begin_compound_output`
4.275 + * `write_files`
4.276 +
4.277 +=== Compound Interfaces ===
4.278 +
4.279 +The `begin_compound_output` function is called by the main program when
4.280 +compound interface generation has been requested. It produces extra output
4.281 +that references and augments output produced for individual interfaces.
4.282 +
4.283 +Various details of individual interfaces are incorporated into the compound
4.284 +interface output. To achieve this, once the `begin_compound_output` function
4.285 +has been called, individual interface output is generated. During this
4.286 +activity, the `write_compound_output` function is called for each individual
4.287 +interface to insert details of that interface into the appropriate place
4.288 +within the compound interface output.
4.289 +
4.290 +The `end_compound_output` function ultimately closes the files involved,
4.291 +either through being invoked by the main program or upon a failure condition.
4.292 +
4.293 +The following diagram summarises the general function organisation involved.
4.294 +
4.295 +######## A graph showing the function organisation involved in generating
4.296 +######## compound interfaces...
4.297 +
4.298 +{{{#!graphviz
4.299 +#format svg
4.300 +#transform notugly
4.301 +digraph compound
4.302 +{
4.303 + graph [fontsize="15.0",fontname="Helvetica"];
4.304 + node [shape=box,fontname="Helvetica",style=filled,fillcolor=white];
4.305 + rankdir=LR;
4.306 +
4.307 + parser [shape=ellipse];
4.308 +
4.309 + subgraph {
4.310 + rank=same;
4.311 + server [shape=folder,fillcolor="#77ff77",label="..._server.{c,cc,h}"];
4.312 + interface [shape=folder,fillcolor="#77ff77",label="..._interface.h"];
4.313 + interfaces [shape=folder,fillcolor="#77ff77",label="..._interfaces.h"];
4.314 + }
4.315 +
4.316 + subgraph {
4.317 + rank=same;
4.318 + main -> yyparse -> parser -> write_files -> write_interfaces;
4.319 + }
4.320 +
4.321 + main -> begin_compound_output;
4.322 + main -> end_compound_output;
4.323 +
4.324 + begin_compound_output -> write_handler_signature;
4.325 + begin_compound_output -> write_dispatcher_signature;
4.326 +
4.327 + write_handler_signature -> server;
4.328 +
4.329 + write_dispatcher_signature -> server;
4.330 +
4.331 + write_files -> write_compound_dispatch_include -> server;
4.332 +
4.333 + write_interfaces -> write_compound_output;
4.334 +
4.335 + write_compound_output -> write_dispatcher_cases -> server;
4.336 + write_compound_output -> write_compound_interface;
4.337 +
4.338 + write_compound_interface -> interface;
4.339 + write_compound_output -> write_include -> interfaces;
4.340 +}
4.341 +}}}
4.342 +
4.343 +######## End of graph.
4.344 +
4.345 +=== Individual Interfaces ===
4.346 +
4.347 +The `write_files` function coordinates the generation of individual interface
4.348 +output.
4.349 +
4.350 +######## A graph showing the function organisation involved in generating
4.351 +######## individual interfaces...
4.352 +
4.353 +{{{#!graphviz
4.354 +#format svg
4.355 +#transform notugly
4.356 +digraph individual
4.357 +{
4.358 + graph [fontsize="15.0",fontname="Helvetica"];
4.359 + node [shape=box,fontname="Helvetica",style=filled,fillcolor=white];
4.360 + rankdir=LR;
4.361 +
4.362 + parser [shape=ellipse];
4.363 +
4.364 + subgraph {
4.365 + rank=same;
4.366 + client [shape=folder,fillcolor="#77ff77",label="..._client.{c,cc,h}"];
4.367 + server [shape=folder,fillcolor="#77ff77",label="..._server.{c,cc,h}"];
4.368 + interface [shape=folder,fillcolor="#77ff77",label="..._interface.h"];
4.369 + }
4.370 +
4.371 + subgraph {
4.372 + rank=same;
4.373 + main -> yyparse -> parser -> write_files -> write_interfaces;
4.374 + }
4.375 +
4.376 + write_interfaces -> write_client_interface;
4.377 + write_interfaces -> write_dispatcher;
4.378 + write_interfaces -> write_dispatcher_signature;
4.379 + write_interfaces -> write_functions;
4.380 + write_interfaces -> write_handler_signature;
4.381 + write_interfaces -> write_include;
4.382 + write_interfaces -> write_interface_definition;
4.383 + write_interfaces -> write_signatures;
4.384 +
4.385 + write_client_interface -> client;
4.386 + write_dispatcher -> server;
4.387 + write_dispatcher_signature -> server;
4.388 + write_functions -> client;
4.389 + write_handler_signature -> server;
4.390 +
4.391 + write_include -> client;
4.392 + write_include -> server;
4.393 +
4.394 + write_interface_definition -> client;
4.395 + write_interface_definition -> interface;
4.396 +
4.397 + write_signatures -> server;
4.398 +}
4.399 +}}}
4.400 +
4.401 +######## End of graph.
4.402 +
4.403 +== Includes and Headers ==
4.404 +
4.405 + * `includes.c`
4.406 +
4.407 +== Interface Definitions ==
4.408 +
4.409 + * `interface.c`
4.410 +
4.411 +== Templates and Output ==
4.412 +
4.413 + * `templates.h`
4.414 +
4.415 +== Servers ==
4.416 +
4.417 + * `server.c`
4.418 +
4.419 +== Dispatchers and Handlers ==
4.420 +
4.421 + * `dispatch.c`
4.422 +
4.423 +== Parameters and Members ==
4.424 +
4.425 + * `declaration.c`
4.426 +
4.427 +== Message Structures and Access ==
4.428 +
4.429 + * `message.c`
4.430 + * `structure.c`
4.431 +
4.432 +== Summaries ==
4.433 +
4.434 + * `summary.c`
5.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
5.2 +++ b/docs/wiki/Downloads Thu Apr 23 00:03:59 2020 +0200
5.3 @@ -0,0 +1,80 @@
5.4 += Downloads =
5.5 +
5.6 +Remember that certain [[../Prerequisites|prerequisites]] are needed for the
5.7 +software to work.
5.8 +
5.9 +== Copyright and Licence ==
5.10 +
5.11 +The idl4re distribution is made available according to the terms of the
5.12 +[[http://www.gnu.org/copyleft/gpl.html|GNU GPL (version 3 or later)]]. See
5.13 +the `docs/COPYING.txt` and `docs/gpl-3.0.txt` files in the source code
5.14 +distribution for details.
5.15 +
5.16 +== Repository ==
5.17 +
5.18 +The source code repository is located at the following location:
5.19 +
5.20 +https://hg.boddie.org.uk/L4Re/idl4re
5.21 +
5.22 +The repository can be cloned using [[https://www.mercurial-scm.org/|Mercurial]]
5.23 +as follows:
5.24 +
5.25 +{{{
5.26 +hg clone https://hg.boddie.org.uk/L4Re/idl4re
5.27 +}}}
5.28 +
5.29 +If you are familiar with version control systems and Mercurial in particular,
5.30 +it can be convenient to use this approach to obtain and update the software,
5.31 +although you should be aware that updates made available in the repository may,
5.32 +if deployed, cause the software to not function correctly on occasion, even if
5.33 +attempts are made to avoid such situations. Therefore, you should choose to
5.34 +update with care and be prepared to switch to a "known working" revision if
5.35 +necessary.
5.36 +
5.37 +== Releases ==
5.38 +
5.39 +{{{#!wiki tip
5.40 +See below for downloadable archives.
5.41 +}}}
5.42 +
5.43 +Releases are tagged in the repository. The currently-supported releases are
5.44 +listed here for convenience:
5.45 +
5.46 +{{{#!table
5.47 +'''Release''' || '''Details'''
5.48 +==
5.49 +0.1 || [[https://hg.boddie.org.uk/idl4re/rev/rel-0-1|changeset]]
5.50 + .. [[https://hg.boddie.org.uk/idl4re/file/rel-0-1|files]]
5.51 +}}}
5.52 +
5.53 +Details of changes introduced in each new release can be found in the
5.54 +[[../Changelog|changelog]].
5.55 +
5.56 +=== Archives ===
5.57 +
5.58 +Downloadable archives are provided below. Choose "get" to download the
5.59 +appropriate file.
5.60 +
5.61 +<<AttachList(,application/x-tar)>>
5.62 +<<AttachList(,application/x-bzip2)>>
5.63 +
5.64 +=== Signatures ===
5.65 +
5.66 +Downloadable archive signatures are provided below. Choose "get" to download
5.67 +the appropriate file.
5.68 +
5.69 +<<AttachList(,text/plain)>>
5.70 +<<AttachList(,application/pgp-signature)>>
5.71 +
5.72 +To verify an archive, download the archive and accompanying signature file to
5.73 +the same location and then run a command of the following form:
5.74 +
5.75 +{{{
5.76 +gpg --verify <signature file> <archive file>
5.77 +}}}
5.78 +
5.79 +For example:
5.80 +
5.81 +{{{
5.82 +gpg --verify idl4re-0.1.tar.bz2.asc idl4re-0.1.tar.bz2
5.83 +}}}
6.1 --- a/docs/wiki/Getting_Started Thu Apr 23 00:03:30 2020 +0200
6.2 +++ b/docs/wiki/Getting_Started Thu Apr 23 00:03:59 2020 +0200
6.3 @@ -2,12 +2,8 @@
6.4
6.5 Although not strictly necessary for the direct use of this software, it is
6.6 likely that the output from this software will be used together with the L4Re
6.7 -distribution. L4Re can be downloaded from the following location:
6.8 -
6.9 -[[http://l4re.org/download.html]]
6.10 -
6.11 -See the [[Prerequisites|prerequisites]] for more details of this and other
6.12 -required software.
6.13 +distribution. See the [[Prerequisites|prerequisites]] for more details of this
6.14 +and other required software.
6.15
6.16 == Building the Software ==
6.17
6.18 @@ -41,27 +37,8 @@
6.19
6.20 == Using the Software ==
6.21
6.22 -The `idl` tool can be run directly, and a manual page is provided to give an
6.23 -overview of the different options and operating modes. To view the manual page
6.24 -on a system where the software has been centrally installed, use the following
6.25 -command:
6.26 -
6.27 -{{{
6.28 -man idl
6.29 -}}}
6.30 -
6.31 -To view the manual page directly from the top level of the idl4re software
6.32 -distribution, use the following command:
6.33 +See the [[idl]] document for more information on running the `idl` tool and
6.34 +additional documentation, most relevant for standalone use.
6.35
6.36 -{{{
6.37 -man -l docs/idl.1
6.38 -}}}
6.39 -
6.40 -=== Applying the Tool within L4Re Packages ===
6.41 -
6.42 -Although the `idl` tool can be run to generate compilable source files, it is
6.43 -much more convenient to invoke it from within a build system. The L4Re build
6.44 -system is based on Makefiles, and the `mk` directory within the idl4re
6.45 -software distribution contains a collection of Makefile-compatible files that
6.46 -integrate the tool and interface files with the L4Re build system so that the
6.47 -tool is invoked automatically when necessary.
6.48 +See the [[L4Re Support]] document for information more directly relevant to
6.49 +use within L4Re build system packages.
7.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
7.2 +++ b/docs/wiki/L4Re_Support Thu Apr 23 00:03:59 2020 +0200
7.3 @@ -0,0 +1,369 @@
7.4 += L4Re Support =
7.5 +
7.6 +The L4Re build system is based on Makefiles, and the `mk` directory within the
7.7 +idl4re software distribution contains a collection of `make`-compatible files
7.8 +that integrate the [[idl|`idl`]] tool and interface files with the L4Re build
7.9 +system so that the tool is invoked automatically when necessary.
7.10 +
7.11 +<<TableOfContents(2)>>
7.12 +
7.13 +To write or adapt a package `Makefile`, some additional definitions and
7.14 +statements are needed to introduce the additional processing steps that take
7.15 +interface descriptions and generate source code from them when needed.
7.16 +
7.17 +######## A diagram showing the processing workflow...
7.18 +
7.19 +{{{#!graphviz
7.20 +#format svg
7.21 +#transform notugly
7.22 +digraph processing {
7.23 + node [shape=folder,fontsize="13.0",fontname="Helvetica"];
7.24 + edge [fontsize="13.0",fontname="Helvetica"];
7.25 + rankdir=LR;
7.26 +
7.27 + interface [label="Interface:\nfile.idl"];
7.28 +
7.29 + subgraph {
7.30 + rank=same;
7.31 + generated [label="Generated sources:\nfile_server.c\nfile_client.c\n..."];
7.32 + existing [label="Existing sources"];
7.33 + }
7.34 +
7.35 + program [label="Output program"];
7.36 +
7.37 + interface -> generated [label="idl"];
7.38 + generated -> program;
7.39 + existing -> program;
7.40 +}
7.41 +}}}
7.42 +
7.43 +######## End of diagram.
7.44 +
7.45 +This document describes the form a package `Makefile` should take and
7.46 +introduces the required elements to integrate interface code generation into
7.47 +the package build process.
7.48 +
7.49 +== Basic Makefile Structure ==
7.50 +
7.51 +The general form of a suitable `Makefile` employing interface generation
7.52 +follows that broadly used within L4Re, with a top-level package employing the
7.53 +following definitions:
7.54 +
7.55 +{{{
7.56 +PKGDIR ?= .
7.57 +L4DIR ?= $(PKGDIR)/../..
7.58 +}}}
7.59 +
7.60 +Appropriate target and build mode definitions may be specified. For example,
7.61 +for a program:
7.62 +
7.63 +{{{
7.64 +TARGET = myserver
7.65 +MODE = shared
7.66 +}}}
7.67 +
7.68 +For a library:
7.69 +
7.70 +{{{
7.71 +TARGET = libserver.a libserver.so
7.72 +}}}
7.73 +
7.74 +Various locations and the inclusion of some rules are useful to define at this
7.75 +point:
7.76 +
7.77 +{{{
7.78 +IDL_DIR = $(L4DIR)/pkg/libsystypes/idl
7.79 +IDL_MK_DIR = $(L4DIR)/idl4re/mk
7.80 +IDL_BUILD_DIR = .
7.81 +IDL_EXPORT_DIR = .
7.82 +
7.83 +include $(IDL_MK_DIR)/idl.mk
7.84 +}}}
7.85 +
7.86 +(These are described below.)
7.87 +
7.88 +Usage of interface descriptions should be defined. For example, for some
7.89 +interfaces employed by client programs in the C language:
7.90 +
7.91 +{{{
7.92 +CLIENT_INTERFACES_C = file mapped_file
7.93 +}}}
7.94 +
7.95 +For interfaces used by C++ server programs:
7.96 +
7.97 +{{{
7.98 +SERVER_INTERFACES_CC = dataspace dataspace_factory
7.99 +}}}
7.100 +
7.101 +After these definitions, it is possible to provide the normal source file
7.102 +definitions which will be augmented by source files generated to support the
7.103 +interfaces.
7.104 +
7.105 +For example, for a client program employing generated C language files:
7.106 +
7.107 +{{{
7.108 +SRC_C = $(call interfaces_to_client_c,$(CLIENT_INTERFACES_C)) \
7.109 + routines.c main.c
7.110 +}}}
7.111 +
7.112 +It is recommended that the "call" generating the interface source files be
7.113 +placed before the other files. This should cause any required headers to be
7.114 +generated first.
7.115 +
7.116 +(It may be the case that more sophisticated dependency handling may remove the
7.117 +above restriction and actually be necessary, too.)
7.118 +
7.119 +Library-related and header-related definitions are typically needed. For
7.120 +example:
7.121 +
7.122 +{{{
7.123 +REQUIRES_LIBS = libipc libsystypes
7.124 +PRIVATE_INCDIR = $(IDL_BUILD_DIR) $(IDL_EXPORT_DIR)
7.125 +}}}
7.126 +
7.127 +As usual, the `Makefile` ends with the appropriate role-specific rule
7.128 +inclusion. For example, for programs:
7.129 +
7.130 +{{{
7.131 +include $(L4DIR)/mk/prog.mk
7.132 +}}}
7.133 +
7.134 +For interface-driven file generation, an accompanying statement is
7.135 +also required:
7.136 +
7.137 +{{{
7.138 +include $(IDL_MK_DIR)/interface_rules.mk
7.139 +}}}
7.140 +
7.141 +This must appear after the role-specific inclusion statement.
7.142 +
7.143 +The following sections describe the different elements of this basic
7.144 +arrangement in more detail.
7.145 +
7.146 +== Interface-Related Settings ==
7.147 +
7.148 +In a Makefile used to build a L4Re component, the following settings can be
7.149 +used to configure the generation of code from interfaces.
7.150 +
7.151 +|| '''Variable''' || '''Purpose''' ||
7.152 +|| `IDL_DIR` || Finding `.idl` files to be processed ||
7.153 +|| `IDL_MK_DIR` || Finding the `idl4re/mk` directory and rule files ||
7.154 +|| `IDL_BUILD_DIR` || The location of generated code for this component ||
7.155 +|| `IDL_EXPORT_DIR` || Exporting interface headers ||
7.156 +
7.157 +The roles of the variables can be summarised in a diagram:
7.158 +
7.159 +######## A diagram showing the locations and the flow of information...
7.160 +
7.161 +{{{#!graphviz
7.162 +#format svg
7.163 +#transform notugly
7.164 +digraph variables {
7.165 + node [shape=folder,fontsize="13.0",fontname="Helvetica"];
7.166 + edge [fontsize="13.0",fontname="Helvetica"];
7.167 + rankdir=LR;
7.168 +
7.169 + IDL_DIR [label="IDL_DIR\nfile.idl\n..."];
7.170 + IDL_BUILD_DIR [label="IDL_BUILD_DIR\nfile_client.c\n..."];
7.171 + IDL_EXPORT_DIR [label="IDL_EXPORT_DIR\nfile_interface.h\n..."];
7.172 +
7.173 + subgraph {
7.174 + rank=same;
7.175 + IDL_MK_DIR [label="IDL_MK_DIR\nidl.mk\n..."];
7.176 + idl [shape=ellipse];
7.177 + }
7.178 +
7.179 + IDL_DIR -> idl -> IDL_BUILD_DIR;
7.180 + IDL_MK_DIR -> idl [style=dashed];
7.181 + idl -> IDL_EXPORT_DIR;
7.182 +}
7.183 +}}}
7.184 +
7.185 +######## End of diagram.
7.186 +
7.187 +Typically, the following kinds of values will be used:
7.188 +
7.189 +|| '''Variable''' || '''Value''' ||
7.190 +|| `IDL_DIR` || A directory containing interfaces ||
7.191 +|| `IDL_MK_DIR` || `$(L4DIR)/idl4re/mk` ||
7.192 +|| `IDL_BUILD_DIR` || `.` ||
7.193 +|| `IDL_EXPORT_DIR` || (See below for discussion.) ||
7.194 +
7.195 +In the case of `IDL_EXPORT_DIR`, the variable needs to indicate the location
7.196 +of interface header files that can be referenced by code needing to use the
7.197 +component interfaces. Where such code resides in the same package, the current
7.198 +directory (`.`) can be used. Where such code resides in other packages, a
7.199 +location is required to export the generated files to those packages.
7.200 +
7.201 +To avoid mixing up any exported ''generated'' interface headers with original
7.202 +''non-generated'' headers, a value of the following form can be used:
7.203 +
7.204 +{{{
7.205 +$(OBJ_BASE)/include/contrib/$(CONTRIB_INCDIR)
7.206 +}}}
7.207 +
7.208 +Here, a header called `file_interface.h` would be exported and included using
7.209 +just this simple name. However, in some cases, there may be other packages
7.210 +exporting headers of the same name, and this may result in confusion.
7.211 +
7.212 +The solution to this is to organise headers (of any kind) in collections.
7.213 +Here, the header could be placed inside a directory called `fsserver` and be
7.214 +included as `fsserver/file_interface.h`. This would be achieved by using a
7.215 +location of the following form:
7.216 +
7.217 +{{{
7.218 +$(OBJ_BASE)/include/contrib/$(CONTRIB_INCDIR)/fsserver
7.219 +}}}
7.220 +
7.221 +== Filename Transformations ==
7.222 +
7.223 +Immediately after the settings, it is typically useful to define some filename
7.224 +transformations:
7.225 +
7.226 +{{{
7.227 +include $(IDL_MK_DIR)/idl.mk
7.228 +}}}
7.229 +
7.230 +These make it easier to define the various interfaces used by a component and
7.231 +to derive the filenames involved using transformation functions such as the
7.232 +following:
7.233 +
7.234 +{{{
7.235 +$(call interfaces_to_client_cc,$(CLIENT_INTERFACES_CC))
7.236 +}}}
7.237 +
7.238 +Remember that a conventional package `Makefile` will be concerned with source
7.239 +files and their compilation. Since interface files will be used to generate
7.240 +files that do not initially exist, knowledge about the names of these
7.241 +generated source files needs to be applied to tell the build system which
7.242 +files it will ultimately need to compile.
7.243 +
7.244 +######## A diagram showing filename transformations...
7.245 +
7.246 +{{{#!graphviz
7.247 +#format svg
7.248 +#transform notugly
7.249 +digraph transformations {
7.250 + node [shape=box,fontsize="13.0",fontname="Helvetica"];
7.251 + edge [fontsize="13.0",fontname="Helvetica"];
7.252 + rankdir=LR;
7.253 +
7.254 + interface [label="file.idl"];
7.255 + client [label="file_client.c"];
7.256 + server [label="file_server.c"];
7.257 +
7.258 + interface -> client [label="interfaces_to_client_c"];
7.259 + interface -> server [label="interfaces_to_server_c"];
7.260 +}
7.261 +}}}
7.262 +
7.263 +######## End of diagram.
7.264 +
7.265 +Various rules are applied in the build system to make sure that source files
7.266 +are then handled appropriately.
7.267 +
7.268 +== Interface Definitions ==
7.269 +
7.270 +After the settings and the inclusion of the `idl.mk` file, it is appropriate
7.271 +to define certain variables describing the use of individual interfaces:
7.272 +
7.273 +|| '''Variable''' || '''Interface Usage''' ||
7.274 +|| `CLIENT_INTERFACES_C` || C language client code ||
7.275 +|| `CLIENT_INTERFACES_CC` || C++ language client code ||
7.276 +|| `SERVER_INTERFACES_C` || C language server code ||
7.277 +|| `SERVER_INTERFACES_CC` || C++ language server code ||
7.278 +
7.279 +These variables reference `.idl` files containing interface descriptions. For
7.280 +example:
7.281 +
7.282 +{{{
7.283 +SERVER_INTERFACES_CC = dataspace mapped_file
7.284 +}}}
7.285 +
7.286 +This indicates that server code in C++ will need to be generated from
7.287 +`dataspace.idl` and `mapped_file.idl`, and rules are generated to ensure that
7.288 +`make` becomes aware of this need.
7.289 +
7.290 +The variables are then employed in filename transformations, described in more
7.291 +detail elsewhere in this document.
7.292 +
7.293 +=== Compound Interfaces ===
7.294 +
7.295 +The `idl` tool also supports compound interfaces which combine individual
7.296 +interface descriptions so that server components can expose multiple
7.297 +interfaces. Here, a naming convention is employed:
7.298 +
7.299 +|| '''Variable''' || '''Details''' ||
7.300 +|| `interface_NAME` || Indicates the program name of a compound object ||
7.301 +|| `interface_INTERFACES` || A list of individual interface descriptions ||
7.302 +
7.303 +The `interface` portion of each variable is replaced by a compound interface
7.304 +name as in the following example:
7.305 +
7.306 +{{{
7.307 +mapped_file_object_NAME = MappedFileObject
7.308 +mapped_file_object_INTERFACES = dataspace file mapped_file sync
7.309 +}}}
7.310 +
7.311 +Thus, the compound interface description `mapped_file_object` employs the
7.312 +stated individual interfaces and program name:
7.313 +
7.314 +######## A diagram showing an example compound interface...
7.315 +
7.316 +{{{#!graphviz
7.317 +#format svg
7.318 +#transform notugly
7.319 +digraph example
7.320 +{
7.321 + graph [fontsize="15.0",fontname="Helvetica",splines=ortho];
7.322 + node [shape=box,fontname="Helvetica",style=filled,fillcolor=white];
7.323 + edge [arrowhead=empty];
7.324 + rankdir=BT;
7.325 +
7.326 + MappedFileObject [label="MappedFileObject\n(from mapped_file_object)"];
7.327 + Dataspace [label="Dataspace\n(from dataspace)"];
7.328 + File [label="File\n(from file)"];
7.329 + MappedFile [label="MappedFile\n(from mapped_file)"];
7.330 + Sync [label="Sync\n(from sync)"];
7.331 +
7.332 + MappedFileObject -> Dataspace;
7.333 + MappedFileObject -> File;
7.334 + MappedFileObject -> MappedFile;
7.335 + MappedFileObject -> Sync;
7.336 +}
7.337 +}}}
7.338 +
7.339 +######## End of diagram.
7.340 +
7.341 +Defining a compound interface would be equivalent to defining an interface as
7.342 +follows, if `idl` were to support this syntax:
7.343 +
7.344 +{{{
7.345 +interface MappedFileObject inherits Dataspace, File, MappedFile, Sync
7.346 +{
7.347 +};
7.348 +}}}
7.349 +
7.350 +(Currently, this syntax is not supported due to limitations with the tool.)
7.351 +
7.352 +Just as with individual interface descriptions, rules are generated to ensure
7.353 +that code supporting compound interfaces is generated from the interface
7.354 +description files.
7.355 +
7.356 +Special variables act as manifests of all compound interface descriptions used
7.357 +in a particular way:
7.358 +
7.359 +|| '''Variable''' || '''Interface Usage''' ||
7.360 +|| `COMP_INTERFACES_C` || C language server code ||
7.361 +|| `COMP_INTERFACES_CC` || C++ language server code ||
7.362 +
7.363 +For example:
7.364 +
7.365 +{{{
7.366 +COMP_INTERFACES_CC = filesystem_object mapped_file_object
7.367 +}}}
7.368 +
7.369 +Here, two compound interfaces are listed for generation as C++ components.
7.370 +Thus, appropriate `_NAME` and `_INTERFACES` variables must be defined to
7.371 +permit the necessary rule generation so that `make` can generate and build all
7.372 +appropriate files.
8.1 --- a/docs/wiki/Prerequisites Thu Apr 23 00:03:30 2020 +0200
8.2 +++ b/docs/wiki/Prerequisites Thu Apr 23 00:03:59 2020 +0200
8.3 @@ -14,7 +14,7 @@
8.4 ==
8.5 L4Re
8.6 (to apply this software) || Tested with repository version r83 \\
8.7 - .. [[http://l4re.org/]]
8.8 + .. [[http://l4re.org/download.html]]
8.9 ==
8.10 MoinLight
8.11 (needed for documentation) || [[http://projects.boddie.org.uk/MoinLight]]
9.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
9.2 +++ b/docs/wiki/idl Thu Apr 23 00:03:59 2020 +0200
9.3 @@ -0,0 +1,21 @@
9.4 += idl =
9.5 +
9.6 +The `idl` tool can be run directly, and a manual page is provided to give an
9.7 +overview of the different options and operating modes. To view the manual page
9.8 +on a system where the software has been centrally installed, use the following
9.9 +command:
9.10 +
9.11 +{{{
9.12 +man idl
9.13 +}}}
9.14 +
9.15 +To view the manual page directly from the top level of the idl4re software
9.16 +distribution, use the following command:
9.17 +
9.18 +{{{
9.19 +man -l docs/idl.1
9.20 +}}}
9.21 +
9.22 +Although the `idl` tool can be run to generate compilable source files, it is
9.23 +much more convenient to invoke it from within a build system. See the [[L4Re
9.24 +Support]] document for details of using the tool within the L4Re build system.
10.1 --- a/docs/wiki/idl4re Thu Apr 23 00:03:30 2020 +0200
10.2 +++ b/docs/wiki/idl4re Thu Apr 23 00:03:59 2020 +0200
10.3 @@ -1,14 +1,16 @@
10.4 = idl4re =
10.5
10.6 +|| [[Getting Started]] || [[Downloads]] || [[Development]] || [[Roadmap]] ||
10.7 +
10.8 The idl4re project is an attempt to support an interface description language
10.9 for components operating in the [[http://l4re.org/|L4 Runtime Environment]],
10.10 -providing a tool - `idl` - that takes interface descriptions and generates
10.11 -code to be incorporated into components, permitting those components to
10.12 -interact with each other without being concerned with the communications
10.13 +providing a tool - [[idl|`idl`]] - that takes interface descriptions and
10.14 +generates code to be incorporated into components, permitting those components
10.15 +to interact with each other without being concerned with the communications
10.16 mechanisms involved.
10.17
10.18 -See the [[Getting Started|getting started]] guide for instructions on
10.19 -building, deploying and running the software.
10.20 +See [[Getting Started]] for instructions on building, deploying and running
10.21 +the software.
10.22
10.23 == Interface Descriptions ==
10.24