flash_v2: host/libcdl/doc/reference.sgml annotate

annotate host/libcdl/doc/reference.sgml @ 334:c9cbf5dfb306

Update documentation licenses to remove restriction on redistributing substantially modified versions, as per discussions with Red Hat. No change in actual contents.

author	bartv
date	Sun, 15 Sep 2002 22:07:58 +0000
parents	d2c90368aeef
children

rev	line source
210 d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1 <!-- {{{ Banner -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3 <!-- =============================================================== -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	4 <!-- -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	5 <!-- reference.sgml -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	6 <!-- -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	7 <!-- The man pages. -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	8 <!-- -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	9 <!-- =============================================================== -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	10 <!-- ####COPYRIGHTBEGIN#### -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	11 <!-- -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	12 <!-- =============================================================== -->
334 c9cbf5dfb306 Update documentation licenses to remove restriction on redistributing bartv parents: 210 diff changeset	13 <!-- Copyright (C) 2000, 2001, 2002 Red Hat, Inc. -->
210 d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	14 <!-- -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	15 <!-- This material may be distributed only subject to the terms -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	16 <!-- and conditions set forth in the Open Publication License, v1.0 -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	17 <!-- or later (the latest version is presently available at -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	18 <!-- http://www.opencontent.org/openpub/) -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	19 <!-- Distribution of the work or derivative of the work in any -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	20 <!-- standard (paper) book form is prohibited unless prior -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	21 <!-- permission obtained from the copyright holder -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	22 <!-- =============================================================== -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	23 <!-- -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	24 <!-- ####COPYRIGHTEND#### -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	25 <!-- =============================================================== -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	26 <!-- #####DESCRIPTIONBEGIN#### -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	27 <!-- -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	28 <!-- Author(s): bartv -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	29 <!-- Contact(s): bartv -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	30 <!-- Date: 2000/02/06 -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	31 <!-- Version: 0.01 -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	32 <!-- -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	33 <!-- ####DESCRIPTIONEND#### -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	34 <!-- =============================================================== -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	35
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	36 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	37
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	38 <chapter id="reference">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	39 <title>CDL Language Specification</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	40
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	41 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	42 This chapter contains reference information for the main &CDL;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	43 commands &cdl-option;, &cdl-component;, &cdl-package; and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	44 &cdl-interface;, followed by the various properties such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	45 &active-if; and &compile; in alphabetical order.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	46 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	47
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	48 <!-- {{{ cdl_option -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	49
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	50 <refentry id="ref.cdl-option">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	51 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	52 <refentrytitle>&cdl-option;</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	53 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	54
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	55 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	56 <refname>Command &cdl-option;</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	57 <refpurpose>Define a single configuration option</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	58 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	59
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	60 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	61 <synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	62 cdl_option <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	63 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	64 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	65 </synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	66 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	67
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	68 <refsect1><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	69 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	70 The option is the basic unit of configurability. Generally each option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	71 corresponds to a single user choice. Typically there is a certain
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	72 amount of information associated with an option to assist the user in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	73 manipulating that option, for example a textual description. There
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	74 will also be some limits on the possible values that the user can
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	75 choose, so an option may be a simple yes-or-no choice or it may be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	76 something more complicated such as an array size or a device name.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	77 Options may have associated constraints, so if that option is enabled
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	78 then certain conditions have to satisfied elsewhere in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	79 configuration. Options usually have direct consequences such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	80 preprocessor <literal>#define</literal> symbols in a configuration
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	81 header file.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	82 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	83 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	84 &cdl-option; is implemented as a Tcl command that takes two arguments,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	85 a name and a body. The name must be a valid C preprocessor identifier:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	86 a sequence of upper or lower case letters, digits or underscores,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	87 starting with a non-digit character; identifiers beginning with an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	88 underscore should normally be avoided because they may clash with
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	89 system packages or with identifiers reserved for use by the compiler.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	90 Within a single configuration, names must be unique. If a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	91 configuration contained two packages which defined the same entity
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	92 <literal>CYGIMP_SOME_OPTION</literal>, any references to that entity
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	93 in a &requires; property or any other expression
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	94 would be ambiguous. It is possible for a given name to be used by two
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	95 different packages if those packages should never be loaded into a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	96 single configuration. For example, architectural HAL packages are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	97 allowed to re-use names because a single configuration cannot target
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	98 two different architectures. For a recommended naming convention see
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	99 <xref linkend="package.contents">.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	100 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	101 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	102 The second argument to <literal>cdl_option</literal> is a body of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	103 properties, typically surrounded by braces so that the Tcl interpreter
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	104 treats it as a single argument. This body will be processed by a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	105 recursive invocation of the Tcl interpreter, extended with additional
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	106 commands for the various properties that are allowed inside a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	107 &cdl-option;. The valid properties are:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	108 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	109
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	110 <variablelist TermLength=16>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	111
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	112 <varlistentry><term><link linkend="ref.active-if">&active-if;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	113 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	114 Allow additional control over the active state of this option.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	115 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	116
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	117 <varlistentry><term><link linkend="ref.calculated">&calculated;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	118 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	119 The option's value is not directly user-modifiable, it is calculated
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	120 using a suitable CDL expression.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	121 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	122
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	123 <varlistentry><term><link linkend="ref.compile">&compile;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	124 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	125 List the source files that should be built if this option is active
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	126 and enabled.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	127 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	128
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	129 <varlistentry><term><link linkend="ref.default-value">&default-value;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	130 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	131 Provide a default value for this option using a CDL expression.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	132 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	133
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	134 <varlistentry><term><link linkend="ref.define">&define;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	135 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	136 Specify additional <literal>#define</literal> symbols that should go
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	137 into the owning package's configuration header file.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	138 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	139
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	140 <varlistentry><term><link linkend="ref.define-format">&define-format;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	141 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	142 Control how the option's value will appear in the configuration header
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	143 file.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	144 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	145
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	146 <varlistentry><term><link linkend="ref.define-proc">&define-proc;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	147 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	148 Use a fragment of Tcl code to output additional data to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	149 configuration header files.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	150 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	151
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	152 <varlistentry><term><link linkend="ref.description">&description;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	153 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	154 Provide a textual description for this option.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	155 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	156
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	157 <varlistentry><term><link linkend="ref.display">&display;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	158 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	159 Provide a short string describing this option.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	160 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	161
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	162 <varlistentry><term><link linkend="ref.doc">&doc;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	163 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	164 The location of on-line documentation for this option.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	165 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	166
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	167 <varlistentry><term><link linkend="ref.flavor">&flavor;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	168 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	169 Specify the nature of this option.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	170 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	171
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	172 <varlistentry><term><link linkend="ref.if-define">&if-define;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	173 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	174 Output a common preprocessor construct to a configuration header file.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	175 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	176
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	177 <varlistentry><term><link linkend="ref.implements">&implements;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	178 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	179 Enabling this option provides one instance of a more general
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	180 interface.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	181 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	182
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	183 <varlistentry><term><link linkend="ref.legal-values">&legal-values;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	184 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	185 Impose constraints on the possible values for this option.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	186 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	187
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	188 <varlistentry><term><link linkend="ref.make">&make;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	189 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	190 An additional custom build step associated with this option, resulting
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	191 in a target that should not go directly into a library.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	192 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	193
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	194 <varlistentry><term><link linkend="ref.make-object">&make-object;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	195 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	196 An additional custom build step associated with this option, resulting
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	197 in an object file that should go into a library.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	198 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	199
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	200 <varlistentry><term><link linkend="ref.no-define">&no-define;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	201 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	202 Suppress the normal generation of a preprocessor
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	203 <literal>#define</literal> symbol in a configuration header file.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	204 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	205
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	206 <varlistentry><term><link linkend="ref.parent">&parent;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	207 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	208 Control the location of this option in the configuration hierarchy.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	209 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	211 <varlistentry><term><link linkend="ref.requires">&requires;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	212 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	213 List constraints that the configuration should satisfy if this option is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	214 active and enabled.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	215 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	216
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	217 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	218
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	219 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	220
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	221 <refsect1><title>Example</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	222 <programlisting format="linespecific" width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	223 cdl_option CYGDBG_INFRA_DEBUG_PRECONDITIONS {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	224 display "Preconditions"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	225 default_value 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	226 description "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	227 This option allows individual control of preconditions.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	228 A precondition is one type of assert, which it is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	229 useful to control separately from more general asserts.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	230 The function is CYG_PRECONDITION(condition,msg)."
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	231 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	232 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	233 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	234
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	235 <refsect1><title>See Also</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	236 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	237 Command <link linkend="ref.cdl-component">&cdl-component;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	238 command <link linkend="ref.cdl-package">&cdl-package;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	239 command <link linkend="ref.cdl-interface">&cdl-interface;</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	240 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	241 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	242
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	243 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	244
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	245 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	246 <!-- {{{ cdl_component -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	247
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	248 <refentry id="ref.cdl-component">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	249 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	250 <refentrytitle>&cdl-component;</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	251 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	252
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	253 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	254 <refname>Command &cdl-component;</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	255 <refpurpose>Define a component, a collection of configuration options</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	256 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	257
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	258 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	259 <synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	260 cdl_component <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	261 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	262 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	263 </synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	264 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	265
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	266 <refsect1><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	267 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	268 A component is a configuration option that can contain additional
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	269 options and sub-components. The body of a &cdl-component; can contain
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	270 the same properties as that of a &cdl-option;. There is an additional
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	271 property, &script; which allows configuration data to be split into
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	272 multiple files. It is also possible for a component body to include
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	273 &cdl-component;, &cdl-option; and &cdl-interface; entities that should
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	274 go below this component in the configuration hierarchy.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	275 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	276 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	277 &cdl-component; is implemented as a Tcl command that takes two
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	278 arguments, a name and a body. The name must be a valid C preprocessor
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	279 identifier: a sequence of upper or lower case letters, digits or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	280 underscores, starting with a non-digit character; identifiers
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	281 beginning with an underscore should normally be avoided because they
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	282 may clash with system packages or with identifiers reserved for use by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	283 the compiler. Within a single configuration, names must be unique. If
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	284 a configuration contained two packages which defined the same entity
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	285 <literal>CYGIMP_SOME_OPTION</literal>, any references to that entity
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	286 in a &requires; property or any other expression would be ambiguous.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	287 It is possible for a given name to be used by two different packages
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	288 if those packages should never be loaded into a single configuration.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	289 For example, architectural HAL packages are allowed to re-use certain
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	290 names because a single configuration cannot target two different
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	291 architectures. For a recommended naming convention see <xref
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	292 linkend="package.contents">.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	293 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	294 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	295 The second argument to &cdl-component; is a body of properties and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	296 other commands, typically surrounded by braces so that the Tcl
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	297 interpreter treats it as a single argument. This body will be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	298 processed by a recursive invocation of the Tcl interpreter, extended
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	299 with additional commands for the various properties that are allowed
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	300 inside a &cdl-component;. The valid commands are:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	301 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	302
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	303 <variablelist TermLength=16>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	304
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	305 <varlistentry><term><link linkend="ref.active-if">&active-if;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	306 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	307 Allow additional control over the active state of this component.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	308 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	309
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	310 <varlistentry><term><link linkend="ref.calculated">&calculated;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	311 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	312 The component's value is not directly user-modifiable, it is calculated
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	313 using a suitable CDL expression.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	314 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	315
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	316 <varlistentry><term><link linkend="ref.cdl-component">&cdl-component</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	317 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	318 Define a sub-component.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	319 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	320
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	321 <varlistentry><term><link linkend="ref.cdl-interface">&cdl-interface;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	322 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	323 Define an interface which should appear immediately below this
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	324 component in the configuration hierarchy.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	325 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	326
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	327 <varlistentry><term><link linkend="ref.cdl-option">&cdl-option;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	328 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	329 Define a configuration option which should appear immediately below
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	330 this component in the configuration hierarchy.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	331 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	332
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	333 <varlistentry><term><link linkend="ref.compile">&compile;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	334 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	335 List the source files that should be built if this component is active
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	336 and enabled.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	337 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	338
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	339 <varlistentry><term><link linkend="ref.default-value">&default-value;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	340 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	341 Provide a default value for this component using a CDL expression.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	342 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	343
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	344 <varlistentry><term><link linkend="ref.define">&define;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	345 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	346 Specify additional <literal>#define</literal> symbols that should go
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	347 into the owning package's configuration header file.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	348 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	349
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	350 <varlistentry><term><link linkend="ref.define-format">&define-format;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	351 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	352 Control how the component's value will appear in the configuration header
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	353 file.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	354 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	355
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	356 <varlistentry><term><link linkend="ref.define-proc">&define-proc;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	357 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	358 Use a fragment of Tcl code to output additional data to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	359 configuration header files.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	360 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	361
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	362 <varlistentry><term><link linkend="ref.description">&description;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	363 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	364 Provide a textual description for this component.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	365 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	366
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	367 <varlistentry><term><link linkend="ref.display">&display;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	368 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	369 Provide a short string describing this component.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	370 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	371
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	372 <varlistentry><term><link linkend="ref.doc">&doc;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	373 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	374 The location of on-line documentation for this component.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	375 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	376
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	377 <varlistentry><term><link linkend="ref.flavor">&flavor;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	378 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	379 Specify the nature of this component.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	380 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	381
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	382 <varlistentry><term><link linkend="ref.if-define">&if-define;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	383 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	384 Output a common preprocessor construct to a configuration header file.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	385 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	386
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	387 <varlistentry><term><link linkend="ref.implements">&implements;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	388 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	389 Enabling this component provides one instance of a more general
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	390 interface.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	391 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	392
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	393 <varlistentry><term><link linkend="ref.legal-values">&legal-values;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	394 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	395 Impose constraints on the possible values for this component.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	396 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	397
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	398 <varlistentry><term><link linkend="ref.make">&make;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	399 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	400 An additional custom build step associated with this component, resulting
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	401 in a target that should not go directly into a library.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	402 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	403
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	404 <varlistentry><term><link linkend="ref.make-object">&make-object;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	405 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	406 An additional custom build step associated with this component, resulting
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	407 in an object file that should go into a library.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	408 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	409
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	410 <varlistentry><term><link linkend="ref.no-define">&no-define;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	411 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	412 Suppress the normal generation of a preprocessor
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	413 <literal>#define</literal> symbol in a configuration header file.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	414 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	415
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	416 <varlistentry><term><link linkend="ref.parent">&parent;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	417 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	418 Control the location of this component in the configuration hierarchy.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	419 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	420
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	421 <varlistentry><term><link linkend="ref.requires">&requires;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	422 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	423 List constraints that the configuration should satisfy if this component is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	424 active and enabled.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	425 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	426
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	427 <varlistentry><term><link linkend="ref.script">&script;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	428 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	429 Include additional configuration information from another
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	430 CDL script
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	431 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	432
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	433 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	434
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	435 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	436
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	437 <refsect1><title>Example</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	438 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	439 <programlisting format="linespecific" width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	440 cdl_component CYGDBG_USE_ASSERTS {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	441 display "Use asserts"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	442 default_value 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	443 description "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	444 If this component is enabled, assertions in the code are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	445 tested at run-time. Assert functions (CYG_ASSERT()) are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	446 defined in 'include/cyg/infra/cyg_ass.h' within the 'install'
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	447 tree. If the component is disabled, these result in no
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	448 additional object code and no checking of the asserted
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	449 conditions."
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	450 script assert.cdl
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	451 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	452 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	453 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	454 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	455
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	456 <refsect1><title>See Also</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	457 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	458 Command <link linkend="ref.cdl-option">&cdl-option;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	459 command <link linkend="ref.cdl-package">&cdl-package;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	460 command <link linkend="ref.cdl-interface">&cdl-interface;</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	461 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	462 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	463
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	464 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	465
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	466 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	467 <!-- {{{ cdl_package -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	468
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	469 <refentry id="ref.cdl-package">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	470 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	471 <refentrytitle>&cdl-package;</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	472 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	473
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	474 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	475 <refname>Command &cdl-package;</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	476 <refpurpose>Define a package, a component that can be distributed</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	477 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	478
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	479 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	480 <synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	481 cdl_package <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	482 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	483 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	484 </synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	485 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	486
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	487 <refsect1><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	488 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	489 A package is a unit of distribution. It is also a configuration option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	490 in that users can choose whether or not a particular package is loaded
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	491 into the configuration, and which version of that package should be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	492 loaded. It is also a component in that it can contain additional
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	493 components and options in a hierarchy.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	494 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	495 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	496 The top-level &CDL; script for a package should begin with a &cdl-package;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	497 command. This can contain most of the properties that can be used in a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	498 &cdl-option; command, and a number of additional ones which apply to a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	499 package as a whole. It is also possible to include &cdl-component;,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	500 &cdl-interface; and &cdl-option; commands in the body of a package.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	501 However all configuration entities that occur at the top level of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	502 script containing the &cdl-package; command are automatically placed
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	503 below that package in the configuration hierarchy, so putting them
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	504 inside the body has no effect.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	505 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	506 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	507 The following properties cannot be used in the body of a &cdl-package;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	508 command:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	509 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	510 <variablelist TermLength=16>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	511
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	512 <varlistentry><term>&flavor;</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	513 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	514 Packages always have the flavor <literal>booldata</literal>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	515 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	516
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	517 <varlistentry><term>&default-value;</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	518 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	519 The value of a package is its version number. This is specified at the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	520 time the package is loaded into the configuration, and cannot be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	521 calculated afterwards. Typically the most recent version of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	522 package will be loaded.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	523 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	524
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	525 <varlistentry><term>&legal-values;</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	526 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	527 The legal values list for a given package is determined by which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	528 versions of that package are installed in the component repository,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	529 and cannot be further constrained in the CDL scripts.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	530 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	531
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	532 <varlistentry><term>&calculated;</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	533 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	534 The value of a package is always selected at the time that it is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	535 loaded into the configuration, and cannot be re-calculated afterwards.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	536 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	537
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	538 <varlistentry><term>&script;</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	539 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	540 This would be redundant since the CDL script containing the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	541 &cdl-package; command acts as that package's script.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	542 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	543
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	544 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	545
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	546 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	547 &cdl-package; is implemented as a Tcl command that takes two
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	548 arguments, a name and a body. The name must be a valid C preprocessor
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	549 identifier: a sequence of upper or lower case letters, digits or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	550 underscores, starting with a non-digit character; identifiers
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	551 beginning with an underscore should normally be avoided because they
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	552 may clash with system packages or with identifiers reserved for use by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	553 the compiler. Packages should always have unique names within a given
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	554 component repository. For a recommended naming convention see <xref
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	555 linkend="package.contents">.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	556 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	557 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	558 The second argument to &cdl-package; is a body of properties and other
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	559 commands, typically surrounded by braces so that the Tcl interpreter
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	560 treats it as a single argument. This body will be processed by a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	561 recursive invocation of the Tcl interpreter, extended with additional
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	562 commands for the various properties that are allowed inside a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	563 &cdl-package;. The valid commands are:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	564 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	565
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	566 <variablelist TermLength=16>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	567
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	568 <varlistentry><term><link linkend="ref.active-if">&active-if;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	569 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	570 Allow additional control over the active state of this package.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	571 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	572
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	573 <varlistentry><term><link linkend="ref.cdl-component">&cdl-component;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	574 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	575 Define a component which should appear immediately below this package
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	576 in the configuration hierarchy.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	577 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	578
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	579 <varlistentry><term><link linkend="ref.cdl-interface">&cdl-interface;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	580 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	581 Define an interface which should appear immediately below this
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	582 package in the configuration hierarchy.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	583 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	584
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	585 <varlistentry><term><link linkend="ref.cdl-option">&cdl-option;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	586 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	587 Define an option which should appear immediately below
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	588 this package in the configuration hierarchy.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	589 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	590
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	591 <varlistentry><term><link linkend="ref.compile">&compile;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	592 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	593 List the source files that should be built for this package.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	594 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	595
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	596 <varlistentry><term><link linkend="ref.define">&define;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	597 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	598 Specify additional <literal>#define</literal> symbols that should go
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	599 into the package's configuration header file.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	600 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	601
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	602 <varlistentry><term><link linkend="ref.define-format">&define-format;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	603 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	604 Control how the package's value will appear in the global
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	605 configuration header file <filename
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	606 class="headerfile">pkgconf/system.h</filename>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	607 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	608
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	609 <varlistentry><term><link linkend="ref.define-header">&define-header;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	610 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	611 Specify the configuration header file that will be generated for this package.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	612 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	613
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	614 <varlistentry><term><link linkend="ref.define-proc">&define-proc;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	615 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	616 Use a fragment of Tcl code to output additional data to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	617 configuration header files.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	618 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	619
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	620 <varlistentry><term><link linkend="ref.description">&description;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	621 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	622 Provide a textual description for this component.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	623 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	624
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	625 <varlistentry><term><link linkend="ref.display">&display;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	626 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	627 Provide a short string describing this component.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	628 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	629
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	630 <varlistentry><term><link linkend="ref.doc">&doc;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	631 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	632 The location of on-line documentation for this component.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	633 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	634
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	635 <varlistentry><term><link linkend="ref.hardware">&hardware;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	636 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	637 This package is tied to specific hardware.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	638 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	639
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	640 <varlistentry><term><link linkend="ref.if-define">&if-define;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	641 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	642 Output a common preprocessor construct to a configuration header file.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	643 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	644
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	645 <varlistentry><term><link linkend="ref.implements">&implements;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	646 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	647 Enabling this component provides one instance of a more general
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	648 interface.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	649 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	650
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	651 <varlistentry><term><link linkend="ref.include-dir">&include-dir;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	652 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	653 Specify the desired location of this package's exported header files in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	654 the install tree.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	655 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	656
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	657 <varlistentry><term><link linkend="ref.include-files">&include-files;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	658 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	659 List the header files that are exported by this package.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	660 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	661
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	662 <varlistentry><term><link linkend="ref.library">&library;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	663 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	664 Specify which library should contain the object files
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	665 generated by building this package.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	666 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	667
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	668 <varlistentry><term><link linkend="ref.make">&make;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	669 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	670 An additional custom build step associated with this component, resulting
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	671 in a target that should not go directly into a library.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	672 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	673
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	674 <varlistentry><term><link linkend="ref.make-object">&make-object;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	675 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	676 An additional custom build step associated with this component, resulting
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	677 in an object file that should go into a library.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	678 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	679
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	680 <varlistentry><term><link linkend="ref.no-define">&no-define;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	681 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	682 Suppress the normal generation of the package's
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	683 <literal>#define</literal> in the global configuration header file
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	684 <filename class="headerfile">pkgconf/system.h</filename>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	685 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	686
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	687 <varlistentry><term><link linkend="ref.parent">&parent;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	688 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	689 Control the location of this package in the configuration hierarchy.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	690 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	691
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	692 <varlistentry><term><link linkend="ref.requires">&requires;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	693 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	694 List constraints that the configuration should satisfy if this package is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	695 active.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	696 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	697
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	698
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	699 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	700
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	701 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	702
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	703 <refsect1><title>Example</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	704 <programlisting format="linespecific" width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	705 cdl_package CYGPKG_INFRA {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	706 display "Infrastructure"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	707 include_dir cyg/infra
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	708 description "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	709 Common types and useful macros.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	710 Tracing and assertion facilities.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	711 Package startup options."
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	712
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	713 compile startup.cxx prestart.cxx pkgstart.cxx userstart.cxx \
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	714 dummyxxmain.cxx null.cxx simple.cxx fancy.cxx buffer.cxx \
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	715 diag.cxx tcdiag.cxx memcpy.c memset.c delete.cxx
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	716 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	717
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	718 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	719 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	720
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	721 <refsect1><title>See Also</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	722 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	723 Command <link linkend="ref.cdl-option">&cdl-option;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	724 command <link linkend="ref.cdl-component">&cdl-component;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	725 command <link linkend="ref.cdl-interface">&cdl-interface;</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	726 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	727 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	728
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	729 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	730
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	731 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	732 <!-- {{{ cdl_interface -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	733
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	734 <refentry id="ref.cdl-interface">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	735 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	736 <refentrytitle>&cdl-interface;</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	737 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	738
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	739 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	740 <refname>Command &cdl-interface;</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	741 <refpurpose>Define an interface, functionality that can be provided by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	742 a number of different implementations.</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	743 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	744
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	745 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	746 <synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	747 cdl_interface <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	748 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	749 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	750 </synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	751 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	752
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	753 <refsect1><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	754 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	755 An interface is a special type of calculated configuration option.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	756 It provides an abstraction mechanism that is often useful in &CDL;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	757 expressions. As an example, suppose that some package relies on the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	758 presence of code that implements the standard kernel scheduling
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	759 interface. However the requirement is no more stringent than this, so
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	760 the constraint can be satisfied by the mlqueue scheduler, the bitmap
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	761 scheduler, or any additional schedulers that may get implemented in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	762 future. A first attempt at expressing the dependency might be:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	763 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	764 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	765 requires CYGSEM_KERNEL_SCHED_MLQUEUE \|\| CYGSEM_KERNEL_SCHED_BITMAP
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	766 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	767 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	768 This constraint is limited, it may need to be changed if a new
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	769 scheduler were to be added to the system. Interfaces provide a way of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	770 expressing more general relationships:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	771 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	772 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	773 requires CYGINT_KERNEL_SCHEDULER
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	774 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	775 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	776 The interface <literal>CYGINT_KERNEL_SCHEDULER</literal> is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	777 <emphasis>implemented</emphasis> by both the mlqueue and bitmap
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	778 schedulers, and may be implemented by future schedulers as well. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	779 value of an interface is the number of implementors that are active
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	780 and enabled, so in a typical configuration only one scheduler will be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	781 in use and the value of the interface will be <literal>1</literal>. If
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	782 all schedulers are disabled then the interface will have a value
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	783 <literal>0</literal> and the &requires; constraint will not be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	784 satisfied.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	785 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	786 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	787 Some component writers may prefer to use the first &requires;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	788 constraint on the grounds that the code will only have been tested
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	789 with the mlqueue and bitmap schedulers and cannot be guaranteed to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	790 work with any new schedulers. Other component writers may take a more
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	791 optimistic view and assume that their code will work with any
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	792 scheduler until proven otherwise.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	793 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	794 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	795 Interfaces must be defined in CDL scripts, just like options,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	796 components and packages. This involves the command &cdl-interface;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	797 which takes two arguments, a name and a body. The name must be a valid
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	798 C preprocessor identifier: a sequence of upper or lower case letters,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	799 digits or underscores, starting with a non-digit character;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	800 identifiers beginning with an underscore should normally be avoided
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	801 because they may clash with system packages or with identifiers
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	802 reserved for use by the compiler. Within a single configuration, names
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	803 must be unique. If a configuration contained two packages which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	804 defined the same entity <literal>CYGIMP_SOME_OPTION</literal>, any
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	805 references to that entity in a &requires; property or any other
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	806 expression would be ambiguous. It is possible for a given name to be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	807 used by two different packages if those packages should never be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	808 loaded into a single configuration. For example, architectural HAL
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	809 packages are allowed to re-use names because a single configuration
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	810 cannot target two different architectures. For a recommended naming
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	811 convention see <xref linkend="package.contents">.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	812 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	813 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	814 The second argument to &cdl-interface; is a body of properties,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	815 typically surrounded by braces so that the Tcl interpreter treats it
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	816 as a single argument. This body will be processed by a recursive
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	817 invocation of the Tcl interpreter, extended with additional commands
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	818 for the various properties that are allowed inside a &cdl-interface;.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	819 The valid properties are a subset of those for a &cdl-option;.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	820 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	821
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	822 <variablelist TermLength=16>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	823
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	824 <varlistentry><term><link linkend="ref.active-if">&active-if;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	825 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	826 Allow additional control over the active state of this interface.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	827 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	828
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	829 <varlistentry><term><link linkend="ref.compile">&compile;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	830 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	831 List the source files that should be built if this interface is active.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	832 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	833
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	834 <varlistentry><term><link linkend="ref.define">&define;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	835 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	836 Specify additional <literal>#define</literal> symbols that should go
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	837 into the owning package's configuration header file.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	838 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	839
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	840 <varlistentry><term><link linkend="ref.define-format">&define-format;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	841 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	842 Control how the interface's value will appear in the configuration header
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	843 file.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	844 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	845
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	846 <varlistentry><term><link linkend="ref.define-proc">&define-proc;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	847 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	848 Use a fragment of Tcl code to output additional data to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	849 configuration header files.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	850 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	851
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	852 <varlistentry><term><link linkend="ref.description">&description;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	853 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	854 Provide a textual description for this interface.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	855 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	856
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	857 <varlistentry><term><link linkend="ref.display">&display;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	858 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	859 Provide a short string describing this interface.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	860 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	861
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	862 <varlistentry><term><link linkend="ref.doc">&doc;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	863 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	864 The location of on-line documentation for this interface.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	865 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	866
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	867 <varlistentry><term><link linkend="ref.flavor">&flavor;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	868 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	869 Interfaces have the <literal>data</literal> flavor by default, but
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	870 they can also be given the <literal>bool</literal> or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	871 <literal>booldata</literal> flavor when necessary. A
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	872 <literal>bool</literal> interface is disabled if there are no active
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	873 and enabled implementors, otherwise it is enabled. A
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	874 <literal>booldata</literal> interface is also disabled if there are no
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	875 active and enabled implementors, otherwise it is enabled and the data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	876 is a number corresponding to the number of these implementors.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	877 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	878
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	879 <varlistentry><term><link linkend="ref.if-define">&if-define;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	880 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	881 Output a common preprocessor construct to a configuration header file.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	882 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	883
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	884 <varlistentry><term><link linkend="ref.implements">&implements;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	885 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	886 If this interface is active it provides one instance of a more general
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	887 interface.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	888 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	889
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	890 <varlistentry><term><link linkend="ref.legal-values">&legal-values;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	891 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	892 Interfaces always have a small numerical value. The &legal-values; can
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	893 be used to apply additional constraints such as an upper limit.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	894 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	895
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	896 <varlistentry><term><link linkend="ref.make">&make;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	897 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	898 An additional custom build step associated with this option, resulting
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	899 in a target that should not go directly into a library.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	900 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	901
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	902 <varlistentry><term><link linkend="ref.make-object">&make-object;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	903 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	904 An additional custom build step associated with this option, resulting
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	905 in an object file that should go into a library.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	906 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	907
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	908 <varlistentry><term><link linkend="ref.no-define">&no-define;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	909 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	910 Suppress the normal generation of a preprocessor
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	911 <literal>#define</literal> symbol in a configuration header file.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	912 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	913
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	914 <varlistentry><term><link linkend="ref.parent">&parent;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	915 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	916 Control the location of this option in the configuration hierarchy.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	917 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	918
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	919 <varlistentry><term><link linkend="ref.requires">&requires;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	920 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	921 List constraints that the configuration should satisfy if this option is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	922 active and enabled.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	923 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	924
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	925 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	926
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	927 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	928 A number of properties are not applicable to interfaces:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	929 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	930 <variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	931
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	932 <varlistentry><term><link linkend="ref.calculated">&calculated;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	933 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	934 Interfaces are always calculated, based on the number of active and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	935 enabled entities that implement the interface.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	936 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	937
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	938 <varlistentry><term><link linkend="ref.default-value">&default-value;</link></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	939 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	940 Interface values are calculated so a &default-value; property would be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	941 meaningless.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	942 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	943
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	944 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	945
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	946 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	947 Interfaces are not containers, so they cannot hold other entities such
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	948 as options or components.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	949 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	950 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	951 A commonly used constraint on interface values takes the form:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	952 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	953 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	954 requires CYGINT_KERNEL_SCHEDULER == 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	955 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	956 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	957 This constraint specifies that there can be only one scheduler in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	958 system. In some circumstances it is possible for the configuration
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	959 tools to detect this pattern and act accordingly, so for example
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	960 enabling the bitmap scheduler would automatically disable the mlqueue
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	961 scheduler.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	962 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	963
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	964 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	965
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	966 <refsect1><title>Example</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	967 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	968 cdl_interface CYGINT_KERNEL_SCHEDULER {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	969 display "Number of schedulers in this configuration"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	970 requires 1 == CYGINT_KERNEL_SCHEDULER
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	971 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	972 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	973 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	974
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	975 <refsect1><title>See Also</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	976 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	977 Property <link linkend="ref.implements">&implements;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	978 command <link linkend="ref.cdl-option">&cdl-option;</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	979 command <link linkend="ref.cdl-component">&cdl-component;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	980 command <link linkend="ref.cdl-package">&cdl-package;</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	981 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	982 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	983
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	984 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	985
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	986 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	987
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	988 <!-- {{{ active_if -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	989
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	990 <refentry id="ref.active-if">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	991 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	992 <refentrytitle>&active-if;</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	993 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	994
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	995 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	996 <refname>Property &active-if;</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	997 <refpurpose>Allow additional control over the active state of an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	998 option or other CDL entity.</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	999 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1000
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1001 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1002 <synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1003 cdl_option <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1004 active_if <condition>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1005 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1006 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1007 </synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1008 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1009
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1010 <refsect1><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1011 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1012 Configuration options or other entities may be either active or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1013 inactive. Typically this is controlled by the option's location in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1014 overall hierarchy. Consider the option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1015 <literal>CYGDBG_INFRA_DEBUG_PRECONDITIONS</literal>, which exists
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1016 below the component <literal>CYGDBG_USE_ASSERT</literal>. If the whole
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1017 component is disabled then the options it contains are inactive: there
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1018 is no point in enabling preconditions unless there is generic
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1019 assertion support; any &requires; constraints associated with
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1020 preconditions are irrelevant; any &compile; property or other
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1021 build-related property is ignored.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1022 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1023 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1024 In some cases the hierarchy does not provide sufficient control over
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1025 whether or not a particular option should be active. For example, the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1026 math library could have support for floating point exceptions which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1027 is only worthwhile if the hardware implements appropriate
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1028 functionality, as specified by the architectural HAL. The relevant
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1029 math library configuration options should remain below the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1030 <literal>CYGPKG_LIBM</literal> package in the overall hierarchy, but
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1031 should be inactive unless there is appropriate hardware support. In
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1032 cases like this an &active-if; property is appropriate.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1033 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1034 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1035 Another common use of &active-if; properties is to avoid excessive
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1036 nesting in the configuration hierarchy. If some option B is only
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1037 relevant if option A is enabled, it is possible to turn A into a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1038 component that contains B. However adding another level to the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1039 hierarchy for a component which will contain just one entry may be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1040 considered excessive. In such cases it is possible for B to have an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1041 &active-if; dependency on A.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1042 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1043 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1044 &active-if; takes a goal expression as argument. For details of goal
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1045 expression syntax see <xref linkend="language.goal-expression">. In
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1046 most cases the goal expression will be very simple, often involving
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1047 just one other option, but more complicated expressions can be used
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1048 when appropriate. It is also possible to have multiple &active-if;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1049 conditions in a single option, in which case all of the conditions
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1050 have to be satisfied if the option is to be active.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1051 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1052 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1053 The &active-if; and &requires; properties have certain similarities,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1054 but they serve a different purpose. Suppose there are two options A
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1055 and B, and option B relies on functionality provided by A. This could
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1056 be expressed as either <literal>active_if A</literal> or as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1057 <literal>requires A</literal>. The points to note are:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1058 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1059 <itemizedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1060
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1061 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1062 If <literal>active_if A</literal> is used and A is disabled or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1063 inactive, then graphical tools will generally prevent any attempt at
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1064 modifying B. For example the text for B could be grayed out, and the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1065 associated checkbutton (if B is a boolean option) would be disabled.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1066 If the user needs the functionality provided by option B then it is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1067 necessary to go to option A first and manipulate it appropriately.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1068 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1069
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1070 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1071 If <literal>requires A</literal> is used and A is disabled or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1072 inactive, graphical tools will still allow B to be manipulated and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1073 enabled. This would result in a new conflict which may get resolved
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1074 automatically or which may need user intervention.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1075 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1076
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1077 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1078 If there are hardware dependencies then an &active-if; condition is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1079 usually the preferred approach. There is no point in allowing the user
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1080 to manipulate a configuration option if the corresponding
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1081 functionality cannot possibly work on the currently-selected hardware.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1082 Much the same argument applies to coarse-grained dependencies, for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1083 example if an option depends on the presence of a TCP/IP stack then an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1084 <literal>active_if CYGPKG_NET</literal> condition is appropriate:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1085 it may be possible to satisfy the condition, but it requires the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1086 fairly drastic step of loading another package; further more, if the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1087 user wanted a TCP/IP stack in the configuration then it would probably
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1088 have been loaded already. </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1089
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1090 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1091 If option B exists to provide additional debugging information about
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1092 the functionality provided by A then again an &active-if; constraint
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1093 is appropriate. There is no point in letting users enable extra
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1094 debugging facilities for a feature that is not actually present.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1095 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1096
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1097 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1098 The configuration system's inference engine will cope equally well
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1099 with &active-if; and &requires; properties. Suppose there is a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1100 conflict because some third option depends on B. If B is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1101 <literal>active_if A</literal> then the inference engine will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1102 attempt to make A active and enabled, and then to enable B if
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1103 necessary. If B <literal>requires A</literal> then the inference
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1104 engine will attempt to enable B and resolve the resulting conflict by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1105 causing A to be both active and enabled. Although the inference occurs
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1106 in a different order, in most cases the effect will be the same.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1107 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1108
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1109 </itemizedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1110
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1111 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1112
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1113 <refsect1><title>Example</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1114 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1115 # Do not provide extra semaphore debugging if there are no semaphores
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1116 cdl_option CYGDBG_KERNEL_INSTRUMENT_BINSEM {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1117 active_if CYGPKG_KERNEL_SYNCH
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1118 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1119 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1120
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1121 # Avoid another level in the configuration hierarchy
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1122 cdl_option CYGSEM_KERNEL_SYNCH_MUTEX_PRIORITY_INHERITANCE_SIMPLE_RELAY {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1123 active_if CYGSEM_KERNEL_SYNCH_MUTEX_PRIORITY_INHERITANCE_SIMPLE
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1124 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1125 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1126
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1127 # Functionality that is only relevant if another package is loaded
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1128 cdl_option CYGSEM_START_UITRON_COMPATIBILITY {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1129 active_if CYGPKG_UITRON
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1130 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1131 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1132
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1133 # Check that the hardware or HAL provide the appropriate functionality
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1134 cdl_option CYGDBG_HAL_DEBUG_GDB_BREAK_SUPPORT {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1135 active_if CYGINT_HAL_DEBUG_GDB_STUBS_BREAK
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1136 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1137 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1138 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1139 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1140
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1141 <refsect1><title>See Also</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1142 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1143 Property <link linkend="ref.requires">&requires;</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1144 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1145 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1146
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1147 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1148
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1149 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1150 <!-- {{{ calculated -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1151
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1152 <refentry id="ref.calculated">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1153 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1154 <refentrytitle>&calculated;</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1155 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1156
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1157 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1158 <refname>Property &calculated;</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1159 <refpurpose>Used if the current option's value is not user-modifiable,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1160 but is calculated using a suitable CDL expression.</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1161 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1162
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1163 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1164 <synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1165 cdl_option <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1166 calculated <expression>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1167 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1168 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1169 </synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1170 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1171
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1172 <refsect1><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1173 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1174 In some cases it is useful to have a configuration option whose value
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1175 cannot be modified directly by the user. This can be achieved using a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1176 &calculated;, which takes a CDL expression as argument (see <xref
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1177 linkend="language.expression"> for a description of expression
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1178 syntax). The configuration system evaluates the expression when the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1179 current package is loaded and whenever there is a change to any other
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1180 option referenced in the expression. The result depends on the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1181 option's flavor:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1182 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1183
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1184 <variablelist TermLength=16>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1185
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1186 <varlistentry><term><literal>flavor none</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1187 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1188 Options with this flavor have no value, so the &calculated;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1189 property is not applicable.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1190 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1191
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1192 <varlistentry><term><literal>flavor bool</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1193 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1194 If the expression evaluates to a non-zero result the option is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1195 enabled, otherwise it is disabled.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1196 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1197
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1198 <varlistentry><term><literal>flavor booldata</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1199 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1200 If the result of evaluating the expression is zero then the option is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1201 disabled, otherwise the option is enabled and its value is the result.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1202 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1203
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1204 <varlistentry><term><literal>flavor data</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1205 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1206 The value of the option is the result of evaluating the expression.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1207 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1208
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1209 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1211 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1212 There are a number of valid uses for calculated options, and there are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1213 also many cases where some other CDL facility would be more
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1214 appropriate. Valid uses of calculated options include the following:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1215 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1216 <itemizedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1217
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1218 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1219 On some target hardware a particular feature may be user-configurable,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1220 while on other targets it is fixed. For example some processors can
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1221 operate in either big-endian or little-endian mode, while other
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1222 processors do not provide any choice. It is possible to have an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1223 option <literal>CYGARC_BIGENDIAN</literal> which is calculated in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1224 some architectural HAL packages but user-modifiable in others.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1225 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1226
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1227 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1228 Calculated options can provide an alternative way for one package to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1229 affect the behavior of another one. Suppose a package may provide two
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1230 possible implementations, a preferred one involving self-modifying
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1231 code and a slower alternative. If the system involves a ROM bootstrap
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1232 then the slower alternative must be used, but it would be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1233 inappropriate to modify the startup option in every HAL to impose
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1234 constraints on this package. Instead it is possible to have a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1235 calculated option whose value is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1236 <literal>{ CYG_HAL_STARTUP == "ROM" }</literal>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1237 and which has appropriate consequences. Arguably this is a spurious
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1238 example, and it should be a user choice whether or not to use
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1239 self-modifying code with a &default-value; based on
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1240 <literal>CYG_HAL_STARTUP</literal>, but that is for the component
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1241 writer to decide.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1242 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1243
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1244 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1245 Sometimes it should be possible to perform a particular test at
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1246 compile-time, for example by using a C preprocessor
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1247 <literal>#if</literal> construct. However the preprocessor has only
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1248 limited functionality, for example it cannot perform string
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1249 comparisons. CDL expressions are more powerful.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1250 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1251
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1252 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1253 Occasionally a particular sub-expression may occur multiple times in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1254 a CDL script. If the sub-expression is sufficiently complex then it
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1255 may be worthwhile to have a calculated option whose value is the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1256 sub-expression, and then reference that calculated option in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1257 appropriate places.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1258 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1259
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1260 </itemizedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1261
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1262 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1263 Alternatives to using calculated options include the following:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1264 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1265 <itemizedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1266
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1267 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1268 CDL <link linkend="language.interface">interfaces</link> are a form of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1269 calculated option intended as an abstraction mechanism. An interface
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1270 can be used to express the concept of <emphasis>any
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1271 scheduler</emphasis>, as opposed to a specific one such as the bitmap scheduler.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1272 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1273
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1274 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1275 If a calculated option would serve only to add additional information
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1276 to a configuration header file, it may be possible to achieve the same
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1277 effect using a <link linkend="ref.define-proc">&define-proc</link>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1278 property or one of the other properties related to header file
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1279 generation.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1280 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1281
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1282 </itemizedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1283
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1284 <tip>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1285 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1286 If the first entry in a &calculated; expression is a negative
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1287 number, for example <literal>calculated -1</literal> then this
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1288 can be misinterpreted as an option instead of as part of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1289 expression. Currently the &calculated; property does not take any
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1290 options, but this may change in future. Option processing halts at the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1291 sequence <literal>--</literal>, so the desired value can be expressed
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1292 safely using
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1293 <literal>calculated -- -1</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1294 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1295 </tip>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1296
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1297 <warning>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1298 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1299 Some of the CDL scripts in current &eCos; releases make excessive use
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1300 of calculated options. This is partly because the recommended
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1301 alternatives were not always available at the time the scripts were
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1302 written. It is also partly because there is still some missing
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1303 functionality, for example &define-proc; properties cannot yet access
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1304 the configuration data so it may be necessary to use &calculated;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1305 properties to access the data and perform the desired manipulation via
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1306 a &CDL; expression. New scripts should use calculated options only in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1307 accordance with the guidelines.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1308 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1309 </warning>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1310
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1311 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1312 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1313 For options with the booldata flavor the current CDL syntax does not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1314 allow the enabled flag and the value to be calculated separately.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1315 Functionality to permit this may be added in a future release.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1316 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1317 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1318
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1319 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1320 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1321 It has been suggested that having options which are not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1322 user-modifiable is potentially confusing, and that a top-level
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1323 <literal>cdl_constant</literal> command should be added to the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1324 language instead of or in addition to the &calculated; property. Such
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1325 a change is under consideration. However because the value of a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1326 calculated option can depend on other options, it is not necessarily
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1327 constant.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1328 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1329 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1330
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1331 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1332
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1333 <refsect1><title>Example</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1334 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1335 # A constant on some target hardware, perhaps user-modifiable on other
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1336 # targets.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1337 cdl_option CYGNUM_HAL_RTC_PERIOD {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1338 display "Real-time clock period"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1339 flavor data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1340 calculated 12500
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1341 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1342 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1343 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1344
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1345 <refsect1><title>See Also</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1346 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1347 Properties <link linkend="ref.default-value">&default-value;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1348 <link linkend="ref.flavor">&flavor;</link> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1349 <link linkend="ref.legal-values">&legal-values;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1350 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1351 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1352
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1353 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1354
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1355 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1356 <!-- {{{ compile -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1357
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1358 <refentry id="ref.compile">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1359 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1360 <refentrytitle>&compile;</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1361 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1362
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1363 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1364 <refname>Property &compile;</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1365 <refpurpose>List the source files that should be built if this option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1366 is active and enabled.</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1367 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1368
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1369 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1370 <synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1371 cdl_option <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1372 compile [-library=libxxx.a] <list of files>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1373 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1374 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1375 </synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1376 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1377
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1378 <refsect1><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1379 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1380 The &compile; property allows component developers to specify source
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1381 files which should be compiled and added to one of the target
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1382 libraries. Usually each source file will end up the library
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1383 <filename>libtarget.a</filename>. It is possible for component writers
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1384 to specify an alternative library for an entire package using the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1385 <link linkend="ref.library">&library;</link> property. Alternatively
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1386 the desired library can be specified on the &compile; line itself. For
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1387 example, to add a particular source file to the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1388 <filename>libextras.a</filename> library the following could be used:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1389 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1390 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1391 cdl_package CYGPKG_IO_SERIAL {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1392 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1393 compile -library=libextras.a common/tty.c
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1394 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1395 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1396 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1397 Details of the build process including such issues as compiler flags
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1398 and the order in which things happen can be found in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1399 <xref linkend="build">.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1400 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1401 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1402 &compile; properties can occur in any of &cdl-option;,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1403 &cdl-component;, &cdl-package; or &cdl-interface;. A &compile;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1404 property has effect if and only if the entity that contains it is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1405 active and enabled. Typically the body of a &cdl-package; will define
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1406 any source files that need to be built irrespective of individual
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1407 options, and each &cdl-component;, &cdl-option;, and &cdl-interface;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1408 will define source files that are more specific. A single &compile;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1409 property can list any number of source files, all destined for the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1410 same library. A &cdl-option; or other entity can contain multiple
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1411 &compile; properties, each of which can specify a different library.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1412 It is possible for a given source file to be specified in &compile;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1413 properties for several different options, in which case the source
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1414 file will get built if any of these options are active and enabled.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1415 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1416 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1417 If the package follows the <link linkend="package.hierarchy">directory
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1418 layout conventions</link> then the configuration tools will search for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1419 the specified source files first in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1420 <filename class="directory">src</filename> subdirectory of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1421 package, then relative to the package directory itself.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1422 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1423
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1424 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1425 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1426 A shortcoming of the current specification of &compile; properties is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1427 that there is no easy way to specify source files that should be built
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1428 unless an option is enabled. It would sometimes be useful to be able
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1429 to say: “if option <literal>A</literal> is enabled then compile
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1430 file <filename>x.c</filename>, otherwise compile file
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1431 <filename>y.c</filename>. There are two simple ways of achieving this:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1432 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1433 <itemizedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1434 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1435 Always compile <filename>y.c</filename>, typically by listing it in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1436 the body of the &cdl-package;, but use
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1437 <literal>#ifndef A</literal> to produce an empty object file if
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1438 option <literal>A</literal> is not enabled. This has the big
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1439 disadvantage that the file always gets compiled and hence for some
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1440 configurations builds will take longer than necessary.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1441 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1442 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1443 Use a &calculated; option whose value is <literal>!A</literal>, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1444 have a <literal>compile y.c</literal> property in its body. This
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1445 has the big disadvantage of adding another calculated option to the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1446 configuration.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1447 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1448 </itemizedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1449 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1450 It is likely that this will be resolved in the future, possibly by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1451 using some sort of expression as the argument to a &compile; property.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1452 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1453 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1454
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1455 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1456 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1457 Currently it is not possible to control the priority of a &compile;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1458 property, in other words the order in which a file gets compiled
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1459 relative to other build steps. This functionality might prove useful
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1460 for complicated packages and should be added.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1461 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1462 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1463 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1464
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1465 <refsect1><title>Example</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1466 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1467 cdl_package CYGPKG_INFRA {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1468 display "Infrastructure"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1469 include_dir cyg/infra
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1470 description "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1471 Common types and useful macros.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1472 Tracing and assertion facilities.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1473 Package startup options."
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1474
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1475 compile startup.cxx prestart.cxx pkgstart.cxx userstart.cxx \
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1476 dummyxxmain.cxx memcpy.c memset.c delete.cxx \
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1477 diag.cxx tcdiag.cxx
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1478 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1479 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1480 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1481
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1482 <refsect1><title>See Also</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1483 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1484 Properties <link linkend="ref.make">make</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1485 <link linkend="ref.make-object">make_object</link> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1486 <link linkend="ref.library">library</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1487 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1488 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1489
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1490 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1491
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1492 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1493 <!-- {{{ default_value -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1494
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1495 <refentry id="ref.default-value">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1496 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1497 <refentrytitle>&default-value;</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1498 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1499
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1500 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1501 <refname>Property &default-value;</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1502 <refpurpose>Provide a default value for this option using a CDL expression.</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1503 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1504
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1505 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1506 <synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1507 cdl_option <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1508 default_value <expression>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1509 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1510 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1511 </synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1512 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1513
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1514 <refsect1><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1515 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1516 The &default-value; property allows the initial value of a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1517 configuration option to depend on other configuration options. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1518 arguments to the property should be a &CDL; expression, see
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1519 <xref linkend="language.expression"> for the syntactic details.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1520 In many cases a simple constant value will suffice, for example:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1521 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1522 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1523 cdl_component CYGPKG_KERNEL_EXCEPTIONS {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1524 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1525 default_value 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1526
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1527 cdl_option CYGSEM_KERNEL_EXCEPTIONS_DECODE {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1528 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1529 default_value 0
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1530 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1531 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1532 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1533 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1534 However it is also possible for an option's default value to depend on
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1535 other options. For example the common HAL package provides some
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1536 support functions that are needed by the &eCos; kernel, but are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1537 unlikely to be useful if the kernel is not being used. This
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1538 relationship can be expressed using:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1539 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1540 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1541 cdl_option CYGFUN_HAL_COMMON_KERNEL_SUPPORT {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1542 ...
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1543 default_value CYGPKG_KERNEL
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1544 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1545 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1546 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1547 If the kernel is loaded then this HAL option is automatically enabled,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1548 although the user can still disable it explicitly should this prove
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1549 necessary. If the kernel is not loaded then the option is disabled,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1550 although it can still be enabled by the user if desired.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1551 &default-value; expressions can be more complicated than this if
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1552 appropriate, and provide a very powerful facility for component
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1553 writers who want their code to “just do the right thing”
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1554 in a wide variety of configurations.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1555 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1556 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1557 The &CDL; configuration system evaluates the &default-value;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1558 expression when the current package is loaded and whenever there is a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1559 change to any other option referenced in the expression. The result
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1560 depends on the option's flavor:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1561 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1562
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1563 <variablelist TermLength=16>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1564
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1565 <varlistentry><term><literal>flavor none</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1566 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1567 Options with this flavor have no value, so the &default-value;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1568 property is not applicable.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1569 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1570
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1571 <varlistentry><term><literal>flavor bool</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1572 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1573 If the expression evaluates to a non-zero result the option is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1574 enabled by default, otherwise it is disabled.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1575 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1576
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1577 <varlistentry><term><literal>flavor booldata</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1578 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1579 If the result of evaluating the expression is zero then the option is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1580 disabled, otherwise the option is enabled and its value is the result.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1581 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1582
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1583 <varlistentry><term><literal>flavor data</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1584 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1585 The default value of the option is the result of evaluating the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1586 expression.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1587 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1588
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1589 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1590
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1591 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1592 A &cdl-option; or other entity can have at most one &default-value;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1593 property, and it is illegal to have both a &calculated; and a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1594 &default-value; property in one body. If an option does not have
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1595 either a &default-value; or a &calculated; property and it does not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1596 have the flavor <literal>none</literal> then the configuration tools
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1597 will assume a default value expression of <literal>0</literal>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1598 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1599 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1600 On occasion it is useful to have a configuration option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1601 <literal>A</literal> which has both a &requires; constraint on some
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1602 other option <literal>B</literal> and a &default-value; expression of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1603 <literal>B</literal>. If option <literal>B</literal> is not enabled
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1604 then <literal>A</literal> will also be disabled by default and no
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1605 conflict arises. If <literal>B</literal> is enabled then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1606 <literal>A</literal> also becomes enabled and again no conflict
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1607 arises. If a user attempts to enable <literal>B</literal> but not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1608 <literal>A</literal> then there will be a conflict. Users should be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1609 able to deduce that the two options are closely interlinked and should
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1610 not be manipulated independently except in very unusual circumstances.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1611 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1612
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1613 <tip>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1614 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1615 If the first entry in a &default-value; expression is a negative
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1616 number, for example <literal>default_value -1</literal> then this
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1617 can be misinterpreted as an option instead of as part of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1618 expression. Currently the &default-value; property does not take any
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1619 options, but this may change in future. Option processing halts at the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1620 sequence <literal>--</literal>, so the desired value can be expressed
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1621 safely using
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1622 <literal>default_value -- -1</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1623 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1624 </tip>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1625
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1626 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1627 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1628 In many cases it would be useful to calculate default values using
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1629 some global preferences, for example:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1630 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1631 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1632 cdl_option CYGIMP_LIBC_STRING_PREFER_SMALL_TO_FAST {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1633 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1634 default_value CYGGLO_CODESIZE > CYGGLO_SPEED
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1635 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1636 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1637 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1638 Such global preference options do not yet exist, but are likely to be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1639 added in a future version.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1640 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1641 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1642
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1643 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1644 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1645 For options with the booldata flavor the current syntax does not allow
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1646 the default values of the enabled flag and the value to be controlled
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1647 separately. Functionality to permit this may be added in a future
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1648 release.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1649 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1650 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1651
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1652 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1653
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1654 <refsect1><title>Example</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1655 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1656 cdl_option CYGDBG_HAL_DEBUG_GDB_THREAD_SUPPORT {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1657 display "Include GDB multi-threading debug support"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1658 requires CYGDBG_KERNEL_DEBUG_GDB_THREAD_SUPPORT
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1659 default_value CYGDBG_KERNEL_DEBUG_GDB_THREAD_SUPPORT
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1660 description "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1661 This option enables some extra HAL code which is needed
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1662 to support multi-threaded source level debugging."
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1663 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1664 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1665 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1666
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1667 <refsect1><title>See Also</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1668 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1669 Properties <link linkend="ref.calculated">&calculated;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1670 <link linkend="ref.flavor">&flavor;</link> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1671 <link linkend="ref.legal-values">&legal-values;</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1672 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1673 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1674
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1675 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1676
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1677 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1678 <!-- {{{ define -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1679
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1680 <refentry id="ref.define">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1681 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1682 <refentrytitle>&define;</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1683 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1684
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1685 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1686 <refname>Property &define;</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1687 <refpurpose>Specify additional <literal>#define</literal> symbols that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1688 should go into the owning package's configuration header file.</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1689 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1690
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1691 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1692 <synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1693 cdl_option <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1694 define [-file=<filename>] [-format=<format>] <symbol>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1695 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1696 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1697 </synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1698 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1699
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1700 <refsect1><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1701 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1702 Normally the configuration system generates a single
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1703 <literal>#define</literal> for each option that is active and enabled,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1704 with the defined symbol being the name of the option. These
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1705 <literal>#define's</literal> go to the package's own configuration
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1706 header file, for example <filename class="HeaderFile">pkgconf/kernel.h</filename>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1707 for kernel configuration options. For the majority of options this is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1708 sufficient. Sometimes it is useful to have more control over which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1709 <literal>#define's</literal> get generated.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1710 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1711 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1712 The &define; property can be used to generate an addition
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1713 <literal>#define</literal> if the option is both active and enabled,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1714 for example:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1715 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1716 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1717 cdl_option CYGNUM_LIBC_STDIO_FOPEN_MAX {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1718 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1719 define FOPEN_MAX
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1720 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1721 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1722 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1723 If this option is given the value 40 then the following
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1724 <literal>#define's</literal> will be generated in the configuration
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1725 header <filename class="HeaderFile">pkgconf/libc.h</filename>:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1726 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1727 <screen width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1728 #define CYGNUM_LIBC_STDIO_FOPEN_MAX 40
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1729 #define FOPEN_MAX 40
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1730 </screen>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1731 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1732 The default <literal>#define</literal> can be suppressed if desired
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1733 using the &no-define; property. This is useful if the symbol should
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1734 only be defined in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1735 <filename class="HeaderFile">pkgconf/system.h</filename> and not in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1736 the package's own configuration header file. The value that will be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1737 used for this <literal>#define</literal> is the same as for the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1738 default one, and depends on the option's flavor as follows:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1739 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1740
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1741 <variablelist TermLength=16>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1742
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1743 <varlistentry><term><literal>flavor none</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1744 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1745 Options with this flavor are always enabled and have no value, so the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1746 constant <literal>1</literal> will be used.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1747 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1748
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1749 <varlistentry><term><literal>flavor bool</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1750 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1751 If the option is disabled then no <literal>#define</literal> will be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1752 generated. Otherwise the constant <literal>1</literal> will be used.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1753 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1754
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1755 <varlistentry><term><literal>flavor booldata</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1756 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1757 If the option is disabled then no <literal>#define</literal> will be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1758 generated. Otherwise the option's current value will be used.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1759 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1760
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1761 <varlistentry><term><literal>flavor data</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1762 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1763 The option's current value will be used.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1764 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1765
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1766 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1767
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1768 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1769 For active options with the <literal>data</literal> flavor, and for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1770 active and enabled options with the <literal>booldata</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1771 flavor, either one or two <literal>#define's</literal> will be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1772 generated. These take the following forms:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1773 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1774 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1775 #define <symbol> <value>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1776 #define <symbol>_<value>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1777 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1778 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1779 For the first <literal>#define</literal> it is possible to control the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1780 format used for the value using a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1781 <literal>-format=<format></literal> option. For example, the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1782 following can be used to output some configuration data as a C string:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1783 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1784 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1785 cdl_option <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1786 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1787 define -format="\\\"%s\\\"" <symbol>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1788 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1789 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1790 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1791 The implementation of this facility involves concatenating the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1792 Tcl command <literal>format</literal>, the format string, and the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1793 string representation of the option's value, and evaluating this in a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1794 Tcl interpreter. Therefore the format string will be processed twice
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1795 by a Tcl parser, and appropriate care has to be taken with quoting.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1796 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1797 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1798 The second <literal>#define</literal> will be generated only if is a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1799 valid C preprocessor macro symbol. By default the symbols generated by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1800 &define; properties will end up in the package's own configuration
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1801 header file. The <literal>-file</literal> option can be used to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1802 specify an alternative destination. At the time of writing the only
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1803 valid alternative definition is <literal>-file=system.h</literal>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1804 which will send the output to the global configuration header file
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1805 <filename class="HeaderFile">pkgconf/system.h</filename>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1806 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1807 <caution>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1808 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1809 Care has to be taken with the <literal>-format</literal> option.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1810 Because the Tcl interpreter's <literal>format</literal> command is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1811 used, this property is subject to any problems with the implementation
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1812 of this in the Tcl library. Generally there should be no problems with
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1813 string data or with integers up to 32 bits, but there may well be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1814 problems if 64-bit data is involved. This issue may be addressed in a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1815 future release.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1816 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1817 </caution>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1818 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1819
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1820 <refsect1><title>Example</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1821 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1822 cdl_component CYG_HAL_STARTUP {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1823 display "Startup type"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1824 flavor data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1825 legal_values {"RAM" "ROM" }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1826 default_value {"RAM"}
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1827 no_define
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1828 define -file=system.h CYG_HAL_STARTUP
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1829 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1830 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1831 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1832 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1833
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1834 <refsect1><title>See Also</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1835 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1836 Properties <link linkend="ref.define-format">&define-format;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1837 <link linkend="ref.define-header">&define-header;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1838 <link linkend="ref.define-proc">&define-proc;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1839 <link linkend="ref.if-define">&if-define;</link> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1840 <link linkend="ref.no-define">&no-define;</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1841 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1842 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1843
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1844 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1845
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1846 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1847 <!-- {{{ define_format -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1848
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1849 <refentry id="ref.define-format">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1850 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1851 <refentrytitle>&define-format;</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1852 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1853
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1854 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1855 <refname>Property &define-format;</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1856 <refpurpose>Control how an option's value will appear in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1857 configuration header file.</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1858 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1859
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1860 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1861 <synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1862 cdl_option <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1863 define_format <format string>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1864 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1865 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1866 </synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1867 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1868
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1869 <refsect1><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1870 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1871 For active options with the <literal>data</literal> flavor, and for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1872 active and enabled options with the <literal>booldata</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1873 flavor, the configuration tools will normally generate two
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1874 <literal>#define's</literal> in the package's configuration header
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1875 file. These take the following forms:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1876 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1877 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1878 #define <name> <value>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1879 #define <name>_<value>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1880 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1881 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1882 The &define-format; property can be used to control exactly what
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1883 appears as the value for the first of these
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1884 <literal>#define's</literal>. For example, the following can be used
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1885 to output some configuration data as a C string:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1886 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1887 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1888 cdl_option <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1889 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1890 define -format="\\\"%s\\\"" <symbol>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1891 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1892 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1893 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1894 The implementation of &define-format; involves concatenating the Tcl
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1895 command <literal>format</literal>, the format string, and the string
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1896 representation of the option's value, and evaluating this in a Tcl
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1897 interpreter. Therefore the format string will be processed twice by a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1898 Tcl parser, and appropriate care has to be taken with quoting.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1899 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1900 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1901 The second <literal>#define</literal> will be generated only if is a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1902 valid C preprocessor macro symbol, and is not affected by the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1903 &define-format; property. Also, the property is only relevant for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1904 options with the <literal>data</literal> or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1905 <literal>booldata</literal> flavor, and cannot be used in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1906 conjunction with the &no-define; property since it makes no sense to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1907 specify the format if no <literal>#define</literal> is generated.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1908 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1909 <caution>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1910 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1911 Because the Tcl interpreter's <literal>format</literal> command is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1912 used, this property is subject to any problems with the implementation
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1913 of this in the Tcl library. Generally there should be no problems with
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1914 string data or with integers up to 32 bits, but there may well be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1915 problems if 64-bit data is involved. This issue may be addressed in a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1916 future release.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1917 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1918 </caution>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1919
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1920 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1921
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1922 <refsect1><title>Example</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1923 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1924 cdl_option CYGNUM_UITRON_VER_ID {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1925 display "OS identification"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1926 flavor data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1927 legal_values 0 to 0xFFFF
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1928 default_value 0
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1929 define_format "0x%04x"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1930 description "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1931 This value is returned in the 'id'
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1932 field of the T_VER structure in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1933 response to a get_ver() system call."
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1934 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1935 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1936 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1937
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1938 <refsect1><title>See Also</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1939 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1940 Properties <link linkend="ref.define">&define;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1941 <link linkend="ref.define-header">&define-header;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1942 <link linkend="ref.define-proc">&define-proc;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1943 <link linkend="ref.if-define">&if-define;</link> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1944 <link linkend="ref.no-define">&no-define;</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1945 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1946 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1947
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1948 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1949
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1950 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1951 <!-- {{{ define_header -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1952
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1953 <refentry id="ref.define-header">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1954 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1955 <refentrytitle>&define-header;</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1956 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1957
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1958 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1959 <refname>Property &define-header;</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1960 <refpurpose>Specify the configuration header file that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1961 will be generated for a given package.</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1962 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1963
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1964 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1965 <synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1966 cdl_package <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1967 define_header <file name>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1968 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1969 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1970 </synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1971 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1972
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1973 <refsect1><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1974 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1975 When the configuration tools generate a build tree, one of the steps
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1976 is to output each package's configuration data to a header file. For
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1977 example the kernel's configuration data gets output to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1978 <filename class="HeaderFile">pkgconf/kernel.h</filename>. This allows
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1979 each package's source code to <literal>#include</literal> the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1980 appropriate header file and adapt to the choices made by the user.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1981 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1982 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1983 By default the configuration tools will synthesize a file name from
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1984 the package name. This involves removing any prefix such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1985 <literal>CYGPKG_</literal>, up to and including the first underscore,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1986 and then converting the remainder of the name to lower case. In some
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1987 cases it may be desirable to use a different header file, for example
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1988 an existing package may have been ported to &eCos; and the source code
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1989 may already <literal>#include</literal> a particular file for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1990 configuration data. In such cases a &define-header; property can be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1991 used to specify an alternative filename.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1992 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1993 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1994 The &define-header; property can only be used in the body of a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1995 &cdl-package; command. It applies to a package as a whole and cannot
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1996 be used at a finer grain. The name specified in a &define-header;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1997 property will always be interpreted as relative to the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1998 <filename class="Directory">include/pkgconf</filename> sub-directory
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	1999 of the install tree.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2000 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2001 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2002 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2003 For hardware-specific packages such as device drivers and HAL
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2004 packages, the current scheme of generating a configuration header file
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2005 name based on the package name may be abandoned. Instead all hardware
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2006 packages would send their configuration data to a single header file,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2007 <filename class="HeaderFile">pkgconf/hardware.h</filename>. This would
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2008 make it easier for code to obtain details of the current hardware, but
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2009 obviously there are compatibility issues. For now it is recommended
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2010 that all hardware packages specify their configuration header file
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2011 explicitly.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2012 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2013 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2014 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2015
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2016 <refsect1><title>Example</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2017 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2018 cdl_package CYGPKG_HAL_ARM {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2019 display "ARM architecture"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2020 parent CYGPKG_HAL
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2021 hardware
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2022 include_dir cyg/hal
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2023 define_header hal_arm.h
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2024 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2025 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2026 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2027 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2028
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2029 <refsect1><title>See Also</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2030 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2031 Properties <link linkend="ref.define">&define;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2032 <link linkend="ref.define-format">&define-format;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2033 <link linkend="ref.define-proc">&define-proc;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2034 <link linkend="ref.if-define">&if-define;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2035 <link linkend="ref.no-define">&no-define;</link> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2036 <link linkend="ref.hardware">&hardware;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2037 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2038 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2039
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2040 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2041
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2042 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2043 <!-- {{{ define_proc -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2044
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2045 <refentry id="ref.define-proc">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2046 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2047 <refentrytitle>&define-proc;</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2048 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2049
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2050 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2051 <refname>Property &define-proc;</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2052 <refpurpose>Use a fragment of Tcl code to output additional data to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2053 configuration header files.</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2054 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2055
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2056 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2057 <synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2058 cdl_option <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2059 define_proc <Tcl script>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2060 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2061 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2062 </synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2063 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2064
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2065 <refsect1><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2066 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2067 For most configuration options it is sufficient to have an entry in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2068 the configuration header file of the form:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2069 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2070 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2071 #define <name> <value>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2072 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2073 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2074 In some cases it is desirable to perform some more complicated
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2075 processing when generating a configuration header file. There are a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2076 number of CDL properties for this, including &define-format; and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2077 &if-define;. The most flexible is &define-proc;: this allows the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2078 component writer to specify a Tcl script that gets invoked whenever
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2079 the configuration system generates the header file for the owning
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2080 package. The script can output anything to the header file, for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2081 example it could generate a C data structure based on various
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2082 configuration values.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2083 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2084 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2085 At the point that the &define-proc; script is invoked there will be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2086 two channels to open files, accessible via Tcl variables:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2087 <literal>cdl_header</literal> is a channel to the current package's
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2088 own header file for example
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2089 <filename class="HeaderFile">pkgconf/kernel.h</filename>;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2090 <literal>cdl_system_header</literal> is a channel to the global
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2091 configuration file
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2092 <filename class="Headerfile">pkgconf/system.h</filename>. A typical
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2093 &define-proc; script will use the <literal>puts</literal> command to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2094 output data to one of these channels.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2095 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2096 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2097 &define-proc; properties only take effect if the current option is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2098 active and enabled. The default behavior of the configuration system
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2099 for an option with the <literal>bool</literal> flavor corresponds to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2100 the following &define-proc;:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2101 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2102 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2103 cdl_option XXX {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2104 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2105 define_proc {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2106 puts $cdl_header "#define XXX 1"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2107 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2108 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2109 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2110 <warning>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2111 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2112 In the current implementation it is not possible for a &define-proc;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2113 property to examine the current values of various configuration
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2114 options and adapt accordingly. This is a major limitation, and will be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2115 addressed in future versions of the configuration tools.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2116 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2117 </warning>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2118
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2119 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2120
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2121 <refsect1><title>Example</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2122 <programlisting width=90>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2123 cdl_package CYGPKG_HAL_ARM_PID {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2124 display "ARM PID evaluation board"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2125 parent CYGPKG_HAL_ARM
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2126 define_header hal_arm_pid.h
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2127 include_dir cyg/hal
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2128 hardware
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2129
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2130 define_proc {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2131 puts $::cdl_system_header "#define CYGBLD_HAL_TARGET_H <pkgconf/hal_arm.h>"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2132 puts $::cdl_system_header "#define CYGBLD_HAL_PLATFORM_H <pkgconf/hal_arm_pid.h>"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2133 puts $::cdl_header ""
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2134 puts $::cdl_header "#define HAL_PLATFORM_CPU \"ARM 7TDMI\""
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2135 puts $::cdl_header "#define HAL_PLATFORM_BOARD \"PID\""
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2136 puts $::cdl_header "#define HAL_PLATFORM_EXTRA \"\""
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2137 puts $::cdl_header ""
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2138 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2139 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2140 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2141 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2142 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2143
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2144 <refsect1><title>See Also</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2145 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2146 Properties <link linkend="ref.define">&define;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2147 <link linkend="ref.define-format">&define-format;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2148 <link linkend="ref.define-header">&define-header;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2149 <link linkend="ref.if-define">&if-define;</link> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2150 <link linkend="ref.no-define">&no-define;</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2151 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2152 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2153
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2154 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2155
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2156 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2157 <!-- {{{ description -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2158
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2159 <refentry id="ref.description">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2160 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2161 <refentrytitle>&description;</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2162 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2163
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2164 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2165 <refname>Property &description;</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2166 <refpurpose>Provide a textual description for an option.</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2167 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2168
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2169 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2170 <synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2171 cdl_option <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2172 description <text>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2173 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2174 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2175 </synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2176 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2177
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2178 <refsect1><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2179 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2180 Users can only be expected to manipulate configuration options
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2181 sensibly if they are given sufficient information about these options.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2182 There are three properties which serve to explain an option in plain
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2183 text: the &display; property gives a textual alias for an option,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2184 which is usually more comprehensible than something like
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2185 <literal>CYGPKG_LIBC_TIME_ZONES</literal>; the &description; property
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2186 gives a longer description, typically a paragraph or so; the &doc;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2187 property specifies the location of additional on-line documentation
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2188 related to a configuration option. In the context of a graphical tool
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2189 the &display; string will be the primary way for users to identify
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2190 configuration options; the &description; paragraph will be visible
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2191 whenever the option is selected; the on-line documentation will only
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2192 be accessed when the user explicitly requests it.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2193 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2194 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2195 At present there is no way of providing any sort of formatting mark-up
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2196 in a description. It is possible that future versions of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2197 configuration tools will provide some control over the way the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2198 description text gets rendered.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2199 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2200 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2201
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2202 <refsect1><title>Example</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2203 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2204 cdl_option CYGDBG_INFRA_DEBUG_TRACE_MESSAGE {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2205 display "Use trace text"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2206 default_value 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2207 description "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2208 All trace calls within eCos contain a text message
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2209 which should give some information about the circumstances.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2210 These text messages will end up being embedded in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2211 application image and hence there is a significant penalty
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2212 in terms of image size.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2213 It is possible to suppress the use of these messages by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2214 disabling this option.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2215 This results in smaller code size, but there is less
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2216 human-readable information available in the trace output,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2217 possibly only filenames and line numbers."
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2218 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2219 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2220 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2221
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2222 <refsect1><title>See Also</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2223 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2224 Properties <link linkend="ref.display">&display;</link> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2225 <link linkend="ref.doc">&doc;</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2226 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2227 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2228
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2229 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2230
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2231 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2232 <!-- {{{ display -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2233
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2234 <refentry id="ref.display">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2235 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2236 <refentrytitle>&display;</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2237 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2238
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2239 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2240 <refname>Property &display;</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2241 <refpurpose>Provide a short string describing this option.</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2242 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2243
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2244 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2245 <synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2246 cdl_option <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2247 display <string>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2248 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2249 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2250 </synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2251 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2252
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2253 <refsect1><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2254 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2255 Users can only be expected to manipulate configuration options
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2256 sensibly if they are given sufficient information about these options.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2257 There are three properties which serve to explain an option in plain
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2258 text: the &display; property gives a textual alias for an option,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2259 which is usually more comprehensible than something like
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2260 <literal>CYGPKG_LIBC_TIME_ZONES</literal>; the &description; property
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2261 gives a longer description, typically a paragraph or so; the &doc;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2262 property specifies the location of additional on-line documentation
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2263 related to a configuration option. In the context of a graphical tool
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2264 the &display; string will be the primary way for users to identify
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2265 configuration options; the &description; paragraph will be visible
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2266 whenever the option is selected; the on-line documentation will only
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2267 be accessed when the user explicitly requests it.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2268 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2269 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2270
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2271 <refsect1><title>Example</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2272 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2273 cdl_option CYGNUM_KERNEL_SYNCH_MBOX_QUEUE_SIZE {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2274 display "Message box queue size"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2275 flavor data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2276 legal_values 1 to 65535
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2277 default_value 10
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2278 description "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2279 This configuration option controls the number of messages
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2280 that can be queued in a message box before a non-blocking
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2281 put() operation will fail or a blocking put() operation will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2282 block. The cost in memory is one pointer per message box for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2283 each possible message."
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2284 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2285 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2286 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2287
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2288 <refsect1><title>See Also</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2289 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2290 Properties <link linkend="ref.description">&description;</link> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2291 <link linkend="ref.doc">&doc;</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2292 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2293 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2294
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2295 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2296
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2297 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2298 <!-- {{{ doc -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2299
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2300 <refentry id="ref.doc">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2301 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2302 <refentrytitle>&doc;</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2303 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2304
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2305 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2306 <refname>Property &doc;</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2307 <refpurpose>The location of online-documentation for a configuration option.</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2308 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2309
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2310 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2311 <synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2312 cdl_option <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2313 doc <URL;>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2314 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2315 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2316 </synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2317 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2318
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2319 <refsect1><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2320 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2321 Users can only be expected to manipulate configuration options
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2322 sensibly if they are given sufficient information about these options.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2323 There are three properties which serve to explain an option in plain
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2324 text: the &display; property gives a textual alias for an option,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2325 which is usually more comprehensible than something like
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2326 <literal>CYGPKG_LIBC_TIME_ZONES</literal>; the &description; property
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2327 gives a longer description, typically a paragraph or so; the &doc;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2328 property specifies the location of additional on-line documentation
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2329 related to a configuration option. In the context of a graphical tool
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2330 the &display; string will be the primary way for users to identify
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2331 configuration options; the &description; paragraph will be visible
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2332 whenever the option is selected; the on-line documentation will only
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2333 be accessed when the user explicitly requests it.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2334 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2335 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2336 The documentation may be an absolute URL, but more generally the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2337 on-line documentation will be shipped with the package and can be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2338 accessed via a relative URL. If the package follows the <link
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2339 linkend="package.hierarchy">directory layout conventions</link> then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2340 the configuration tools will search for the specified html file
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2341 first in the <filename class="directory">doc</filename> subdirectory
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2342 of the package, then relative to the package directory itself. The URL
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2343 may contain a <literal>#</literal> character to specify an anchor
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2344 within a page.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2345 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2346 <warning>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2347 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2348 At the time of writing the &eCos; packages in the standard
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2349 distribution do not conform to the directory layout conventions when
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2350 it comes to the documentation. Instead of organizing the documentation
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2351 on a per-package basis and placing it in the corresponding
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2352 <filename class="directory">doc</filename> sub-directories, all the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2353 documentation is kept in a central location. This should get addressed
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2354 in a future release of the system. Third party component writers
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2355 should follow the layout conventions.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2356 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2357 </warning>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2358 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2359
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2360 <refsect1><title>Example</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2361 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2362 cdl_package CYGPKG_KERNEL {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2363 display "eCos kernel"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2364 doc ref/ecos-ref.4.html
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2365 include_dir cyg/kernel
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2366 description "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2367 This package contains the core functionality of the eCos
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2368 kernel. It relies on functionality provided by various HAL
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2369 packages and by the eCos infrastructure. In turn the eCos
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2370 kernel provides support for other packages such as the device
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2371 drivers and the uITRON compatibility layer."
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2372 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2373 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2374 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2375 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2376
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2377 <refsect1><title>See Also</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2378 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2379 Properties <link linkend="ref.description">&description;</link> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2380 <link linkend="ref.display">&display;</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2381 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2382 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2383
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2384 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2385
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2386 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2387 <!-- {{{ flavor -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2388
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2389 <refentry id="ref.flavor">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2390 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2391 <refentrytitle>&flavor;</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2392 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2393
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2394 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2395 <refname>Property &flavor;</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2396 <refpurpose>Specify the nature of a configuration option.</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2397 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2398
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2399 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2400 <synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2401 cdl_option <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2402 flavor <flavor>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2403 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2404 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2405 </synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2406 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2407
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2408 <refsect1><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2409 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2410 The state of a &CDL; configuration option is a somewhat complicated
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2411 concept. This state determines what happens when a build tree is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2412 generated: it controls what files get built and what
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2413 <literal>#define's</literal> end up in configuration header files. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2414 state also controls the values used during expression evaluation. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2415 key concepts are:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2416 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2417 <orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2418 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2419 An option may or may not be loaded into the current configuration.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2420 However it is still possible for packages to reference options which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2421 are not loaded in a &requires; constraint or other expression. If an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2422 option is not loaded then it will have no direct effect on the build
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2423 process, and <literal>0</literal> will be used for expression
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2424 evaluation.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2425 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2426
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2427 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2428 Even if an option is loaded it may still be inactive. Usually this is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2429 controlled by the option's location in the configuration hierarchy. If
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2430 an option's parent is active and enabled then the option will normally
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2431 be active. If the parent is either inactive or disabled then the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2432 option will be inactive. For example, if kernel timeslicing is diabled
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2433 then the option <literal>CYGNUM_KERNEL_SCHED_TIMESLICE_TICKS</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2434 is irrelevant and must have no effect. The &active-if; property can be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2435 used to specify additional constraints. If an option is inactive then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2436 it will have no direct effect on the build process, in other words it
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2437 will not cause any files to get built or <literal>#define's</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2438 to be generated. For the purposes of expression evaluation an inactive
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2439 option has a value of <literal>0</literal>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2440 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2441
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2442 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2443 An option may be enabled or disabled. Most options are boolean in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2444 nature, for example a particular function may get inlined or it may
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2445 involve a full procedure call. If an option is disabled then it has no
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2446 direct effect on the build process, and for the purposes of expression
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2447 evaluation it has a value of 0.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2448 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2449 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2450 An option may also have additional data associated with it, for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2451 example a numerical value used to control the size of an array.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2452 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2453 </orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2454 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2455 Most options are boolean in nature and do not have any additional
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2456 associated data. For some options only the data part makes sense and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2457 users should be unable to manipulate the enabled/disabled part of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2458 state. For a comparatively small number of options it makes sense to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2459 have the ability to disable that option or to enable it and associate
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2460 data as well. Finally, when constructing an option hierarchy it is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2461 occasionally useful to have entities which serve only as placeholders.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2462 The &flavor; property can be used to control all this. There are four
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2463 possible values. It should be noted that the active or inactive state
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2464 of an option takes priority over the flavor: if an option is inactive
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2465 then no <literal>#define's</literal> will be generated and any
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2466 build-related properties such as &compile; will be ignored.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2467 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2468
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2469 <variablelist TermLength=16>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2470
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2471 <varlistentry><term>flavor <literal>none</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2472 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2473 The <literal>none</literal> is intended primarily for placeholder
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2474 components in the hierarchy, although it can be used for other
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2475 purposes. Options with this flavor are always enabled and do not have
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2476 any additional data associated with them, so there is no way for users
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2477 to modify the option. For the purposes of expression evaluation an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2478 option with flavor <literal>none</literal> always has the value
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2479 <literal>1</literal>. Normal <literal>#define</literal> processing
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2480 will take place, so typically a single <literal>#define</literal> will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2481 be generated using the option name and a value of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2482 <literal>1</literal>. Similarly build-related properties such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2483 &compile; will take effect.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2484 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2485
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2486 <varlistentry><term>flavor <literal>bool</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2487 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2488 Boolean options can be either enabled or disabled, and there is no
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2489 additional data associated with them. If a boolean option is disabled
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2490 then no <literal>#define</literal> will be generated and any
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2491 build-related properties such as &compile; will be ignored. For the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2492 purposes of expression evaluation a disabled option has the value
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2493 <literal>0</literal>. If a boolean option is enabled then normal
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2494 <literal>#define</literal> processing will take place, all
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2495 build-related properties take effect, and the option's value will be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2496 <literal>1</literal>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2497 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2498
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2499 <varlistentry><term>flavor <literal>data</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2500 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2501 Options with this flavor are always enabled, and have some additional
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2502 data associated with them which can be edited by the user. This data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2503 can be any sequence of characters, although in practice the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2504 &legal-values; property will often be used to impose constraints. In
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2505 appropriate contexts such as expressions the configuration tools will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2506 attempt to interpret the data as integer or floating point numbers.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2507 Since an option with the <literal>data</literal> flavor cannot be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2508 disabled, normal <literal>#define</literal> processing takes place and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2509 the data will be used for the value. Similarly all build-related
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2510 properties take effect, and the option's value for the purposes of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2511 expression evaluation is the data.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2512 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2513
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2514 <varlistentry><term>flavor <literal>booldata</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2515 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2516 This combines the <literal>bool</literal> and <literal>data</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2517 flavors. The option may be enabled or disabled, and in addition the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2518 option has some associated data. If the option is disabled then no
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2519 <literal>#define</literal> will be generated, the build-related
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2520 properties have no effect, and for the purposes of expression
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2521 evaluation the option's value is <literal>0</literal>. If the option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2522 is enabled then a <literal>#define</literal> will be generated using
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2523 the data as the value, all build-related properties take effect, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2524 the option's value for the purposes of expression evaluation is the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2525 data. If <literal>0</literal> is legal data then it is not possible to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2526 distinguish this case from the option being disabled or inactive.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2527 </para></listitem></varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2528
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2529 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2530
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2531 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2532 Options and components have the <literal>bool</literal> flavor by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2533 default, but this can be changed as desired. Packages always have the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2534 <literal>booldata</literal> flavor, and this cannot be changed.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2535 Interfaces have the <literal>data</literal> flavor by default, since
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2536 the value of an interface is a count of the number of active and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2537 enabled interfaces, but they can be given the <literal>bool</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2538 or <literal>booldata</literal> flavors.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2539 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2540
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2541 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2542 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2543 The expression syntax needs to be extended to allow the loaded,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2544 active, enabled and data aspects of an option's state to be examined
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2545 individually. This would allow component writers to distinguish
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2546 between a disabled <literal>booldata</literal> option and an enabled
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2547 one which has a value of <literal>0</literal>. Such an enhancement to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2548 the expression syntax may also prove useful in other circumstances.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2549 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2550 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2551
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2552 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2553
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2554 <refsect1><title>Example</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2555 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2556
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2557 cdl_component CYGPKG_LIBM_COMPATIBILITY {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2558
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2559 cdl_component CYGNUM_LIBM_COMPATIBILITY {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2560 flavor booldata
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2561 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2562
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2563 cdl_option CYGNUM_LIBM_COMPAT_DEFAULT {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2564 flavor data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2565 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2566 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2567 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2568
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2569 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2570 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2571
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2572 cdl_component CYGPKG_LIBM_TRACE {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2573 flavor bool
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2574 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2575 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2576 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2577 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2578
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2579 <refsect1><title>See Also</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2580 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2581 Properties <link linkend="ref.calculated">&calculated;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2582 <link linkend="ref.default-value">&default-value;</link> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2583 <link linkend="ref.legal-values">&legal-values;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2584 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2585 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2586
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2587 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2588
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2589 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2590 <!-- {{{ hardware -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2591
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2592 <refentry id="ref.hardware">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2593 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2594 <refentrytitle>&hardware;</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2595 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2596
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2597 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2598 <refname>Property &hardware;</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2599 <refpurpose>Specify that a package is tied to specific hardware.</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2600 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2601
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2602 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2603 <synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2604 cdl_option <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2605 active_if <condition>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2606 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2607 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2608 </synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2609 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2610
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2611 <refsect1><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2612 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2613 Some packages such as device drivers and HAL packages are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2614 hardware-specific, and generally it makes no sense to add such
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2615 packages to a configuration unless the corresponding hardware is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2616 present on your target system. Typically hardware package selection
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2617 happens automatically when you select your target. The &hardware;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2618 property can be used in the body of a &cdl-package; command to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2619 indicate that the package is hardware-specific.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2620 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2621
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2622 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2623 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2624 At the time of writing the &hardware; property is largely ignored by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2625 the configuration tools, but this may change in future. Amongst other
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2626 possible changes, for hardware-specific packages such as device
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2627 drivers and HAL packages, the current scheme of generating a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2628 configuration header file name based purely on the package name may be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2629 abandoned. Instead all hardware packages would send their
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2630 configuration data to a single header file, <filename
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2631 class="HeaderFile">pkgconf/hardware.h</filename>. This would make it
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2632 easier for code to obtain details of the current hardware, but
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2633 obviously there are compatibility issues. For now it is recommended
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2634 that all hardware packages specify their configuration header file
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2635 explicitly.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2636 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2637 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2638 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2639
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2640 <refsect1><title>Example</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2641 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2642 cdl_package CYGPKG_HAL_ARM {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2643 display "ARM architecture"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2644 parent CYGPKG_HAL
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2645 hardware
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2646 include_dir cyg/hal
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2647 define_header hal_arm.h
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2648 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2649 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2650 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2651 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2652
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2653 <refsect1><title>See Also</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2654 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2655 Property <link linkend="ref.define-header">&define-header;</link>, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2656 command <link linkend="ref.cdl-package">&cdl-package;</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2657 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2658 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2659
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2660 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2661
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2662 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2663 <!-- {{{ if_define -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2664
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2665 <refentry id="ref.if-define">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2666 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2667 <refentrytitle>&if-define;</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2668 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2669
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2670 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2671 <refname>Property &if-define;</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2672 <refpurpose>Output a common preprocessor construct to a configuration
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2673 header file.</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2674 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2675
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2676 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2677 <synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2678 cdl_option <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2679 if_define [-file=<filename>] <symbol1> <symbol2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2680 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2681 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2682 </synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2683 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2684
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2685 <refsect1><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2686 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2687 The purpose of the &if-define; property is best explained by an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2688 example. Suppose you want finer-grained control over assertions, say
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2689 on a per-package or even a per-file basis rather than globally. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2690 assertion macros can be defined by an exported header file in an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2691 infrastructure package, using code like the following:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2692 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2693 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2694 #ifdef CYGDBG_USE_ASSERTS
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2695 # define CYG_ASSERT( _bool_, _msg_ ) \
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2696 CYG_MACRO_START \
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2697 if ( ! ( _bool_ ) ) \
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2698 CYG_ASSERT_DOCALL( _msg_ ); \
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2699 CYG_MACRO_END
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2700 #else
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2701 # define CYG_ASSERT( _bool_, _msg_ ) CYG_EMPTY_STATEMENT
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2702 #endif
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2703 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2704 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2705 Assuming this header file is <literal>#include'd</literal> directly or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2706 indirectly by any code which may need to be built with assertions
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2707 enabled, the challenge is now to control whether or not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2708 <varname>CYGDBG_USE_ASSERTS</varname> is defined for any given source
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2709 file. This is the purpose of the &if-define; property:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2710 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2711 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2712 cdl_option CYGDBG_KERNEL_USE_ASSERTS {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2713 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2714 if_define CYGSRC_KERNEL CYGDBG_USE_ASSERTS
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2715 requires CYGDBG_INFRA_ASSERTION_SUPPORT
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2716 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2717 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2718 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2719 If this option is active and enabled then the kernel's configuration
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2720 header file would end up containing the following:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2721 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2722 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2723 #ifdef CYGSRC_KERNEL
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2724 # define CYGDBG_USE_ASSERTS 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2725 #endif
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2726 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2727 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2728 Kernel source code can now begin with the following construct:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2729 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2730 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2731 #define CYGSRC_KERNEL 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2732 #include <pkgconf/kernel.h>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2733 #include <cyg/infra/cyg_ass.h>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2734 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2735 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2736 The configuration option only affects kernel source code, assuming
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2737 nothing else <literal>#define's</literal> the symbol
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2738 <varname>CYGSRC_KERNEL</varname>. If the per-package assertion option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2739 is disabled then <varname>CYGDBG_USE_ASSERTS</varname> will not get
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2740 defined. If the option is enabled then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2741 <varname>CYGDBG_USE_ASSERTS</varname> will get defined and assertions
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2742 will be enabled for the kernel sources. It is possible to use the same
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2743 mechanism for other facilities such as tracing, and to apply it at a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2744 finer grain such as individual source files by having multiple options
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2745 with &if-define; properties and multiple symbols such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2746 <varname>CYGSRC_KERNEL_SCHED_BITMAP_CXX</varname>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2747 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2748 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2749 The &if-define; property takes two arguments, both of which must be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2750 valid C preprocessor symbols. If the current option is active and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2751 enabled then three lines will be output to the configuration header
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2752 file:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2753 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2754 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2755 #ifdef <symbol1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2756 # define <symbol2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2757 #endif
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2758 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2759 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2760 If the option is inactive or disabled then these lines will not be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2761 output. By default the current package's configuration header file
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2762 will be used, but it is possible to specify an alternative destination
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2763 using a <literal>-file</literal> option. At present the only
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2764 legitimate alternative destination is <literal>system.h</literal>, the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2765 global configuration header. &if-define; processing happens in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2766 addition to, not instead of, the normal <literal>#define</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2767 processing or the handling of other header-file related properties.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2768 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2769 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2770 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2771 The infrastructure in the current &eCos; release does not yet work
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2772 this way. In future it may do so, and the intention is that suitable
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2773 configuration options get generated semi-automatically by the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2774 configuration system rather than having to be defined explicitly.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2775 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2776 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2777 <tip>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2778 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2779 As an alternative to changing the configuration, updating the build
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2780 tree, and so on, it is possible to enable assertions by editing a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2781 source file directly, for example:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2782 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2783 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2784 #define CYGSRC_KERNEL 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2785 #define CYGDBG_USE_ASSERTS 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2786 #include <pkgconf/kernel.h>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2787 #include <cyg/infra/cyg_ass.h>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2788 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2789 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2790 The assertion header file does not care whether
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2791 <varname>CYGDBG_USE_ASSERTS</varname> is <literal>#define'd</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2792 via a configuration option or by explicit code. This technique can be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2793 useful to component writers when debugging their source code, although
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2794 care has to be taken to remove any such <literal>#define's</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2795 later on.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2796 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2797 </tip>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2798
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2799 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2800
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2801 <refsect1><title>Example</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2802 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2803 cdl_option CYGDBG_KERNEL_USE_ASSERTS {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2804 display "Assertions in the kernel package"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2805 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2806 if_define CYGSRC_KERNEL CYGDBG_USE_ASSERTS
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2807 requires CYGDBG_INFRA_ASSERTION_SUPPORT
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2808 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2809 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2810 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2811
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2812 <refsect1><title>See Also</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2813 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2814 Properties <link linkend="ref.define">&define;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2815 <link linkend="ref.define-format">&define-format;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2816 <link linkend="ref.define-header">&define-header;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2817 <link linkend="ref.define-proc">&define-proc;</link> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2818 <link linkend="ref.no-define">&no-define;</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2819 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2820 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2821
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2822 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2823
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2824 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2825 <!-- {{{ implements -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2826
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2827 <refentry id="ref.implements">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2828 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2829 <refentrytitle>&implements;</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2830 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2831
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2832 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2833 <refname>Property &implements;</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2834 <refpurpose>Enabling this option provides one instance of a more
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2835 general interface.</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2836 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2837
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2838 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2839 <synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2840 cdl_option <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2841 implements <interface>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2842 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2843 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2844 </synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2845 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2846
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2847 <refsect1><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2848 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2849 The &CDL; interface concept provides an abstraction mechanism that can
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2850 be useful in many different circumstances. Essentially an interface is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2851 a calculated option whose value is the number of active and enabled
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2852 options which implement that interface. For example the interface
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2853 <varname>CYGINT_KERNEL_SCHEDULER</varname> has a value corresponding
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2854 to the number of schedulers in the system, typically just one.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2855 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2856 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2857 The &implements; property takes a single argument, which should be the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2858 name of an interface. This interface may be defined in the same
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2859 package as the implementor or in some other package. In the latter
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2860 case it may sometimes be appropriate for the implementor or the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2861 implementor's package to have a &requires; property for the package
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2862 containing the interface. An option may contain multiple &implements;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2863 properties. It is possible for an option to implement a given
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2864 interface multiple times, and on occasion this is actually useful.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2865 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2866 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2867
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2868 <refsect1><title>Example</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2869 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2870 cdl_option CYGSEM_KERNEL_SCHED_MLQUEUE {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2871 display "Multi-level queue scheduler"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2872 default_value 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2873 implements CYGINT_KERNEL_SCHEDULER
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2874 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2875 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2876 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2877 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2878
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2879 <refsect1><title>See Also</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2880 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2881 Command <link linkend="ref.cdl-interface">&cdl-interface;</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2882 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2883 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2884
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2885 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2886
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2887 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2888 <!-- {{{ include_dir -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2889
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2890 <refentry id="ref.include-dir">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2891 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2892 <refentrytitle>&include-dir;</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2893 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2894
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2895 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2896 <refname>Property &include-dir;</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2897 <refpurpose>Specify the desired location of a package's exported
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2898 header files in the install tree.</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2899 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2900
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2901 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2902 <synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2903 cdl_package <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2904 include_dir <sub-directory>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2905 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2906 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2907 </synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2908 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2909
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2910 <refsect1><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2911 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2912 Most packages export one or more header files defining their public
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2913 interface. For example the C library exports header files such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2914 <filename class="HeaderFile">stdio.h</filename> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2915 <filename class="HeaderFile">ctype.h</filename>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2916 If the package follows the <link linkend="package.hierarchy">directory
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2917 layout conventions</link> then the exported header files will normally
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2918 be found in the package's
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2919 <filename class="directory">include</filename> sub-directory.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2920 Alternatively the &include-files; property can be used to specify
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2921 which header files should be exported.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2922 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2923 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2924 By default a package's exported header files will be copied to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2925 the <filename class="directory">include</filename> sub-directory of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2926 the install tree. This is correct for packages like the C library
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2927 because that is the correct location for files such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2928 <filename class="HeaderFile">stdio.h</filename>. However to reduce the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2929 probability of name clashes it is desirable for packages to use
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2930 different sub-directories, for example infrastructure header files get
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2931 copied to <filename class="directory">include/cyg/infra</filename>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2932 rather than to the top-level
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2933 <filename class="directory">include</filename> directory itself.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2934 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2935 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2936 It would be possible to replicate these sub-directories in each
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2937 package's source tree, such that the infrastructure header file
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2938 sources lived in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2939 <filename class="directory">include/cyg/infra</filename> in the source
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2940 tree as well as in the install tree. This would make things more
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2941 difficult for the package developers. Instead it is possible to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2942 specify the desired install tree sub-directory using an &include-dir;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2943 property, for example <literal>include_dir cyg/infra</literal>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2944 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2945 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2946 The &include-dir; property can only be used in the body of a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2947 &cdl-package; command, since it applies to all of the header files
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2948 exported by a package, and only one &include-dir; property can be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2949 used. If there is no &include-dir; property then exported header files
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2950 will end up in the top-level <filename class="directory">include</filename>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2951 directory of the install tree.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2952 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2953 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2954
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2955 <refsect1><title>Example</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2956 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2957 cdl_package CYGPKG_INFRA {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2958 display "Infrastructure"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2959 include_dir cyg/infra
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2960 description "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2961 Common types and useful macros.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2962 Tracing and assertion facilities.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2963 Package startup options."
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2964 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2965 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2966 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2967 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2968
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2969 <refsect1><title>See Also</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2970 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2971 Property <link linkend="ref.include-files">&include-files;</link>, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2972 command <link linkend="ref.cdl-package">&cdl-package;</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2973 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2974 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2975
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2976 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2977
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2978 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2979 <!-- {{{ include_files -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2980
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2981 <refentry id="ref.include-files">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2982 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2983 <refentrytitle>&include-files;</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2984 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2985
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2986 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2987 <refname>Property &include-files;</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2988 <refpurpose>List the header files that are exported by a package.</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2989 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2990
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2991 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2992 <synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2993 cdl_package <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2994 include_files <file1> …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2995 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2996 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2997 </synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2998 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	2999
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3000 <refsect1><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3001 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3002 Most packages export one or more header files defining their public
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3003 interface. For example the C library exports header files such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3004 <filename class="HeaderFile">stdio.h</filename> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3005 <filename class="HeaderFile">ctype.h</filename>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3006 If the package follows the <link linkend="package.hierarchy">directory
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3007 layout conventions</link> then the exported header files will normally
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3008 be found in the package's
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3009 <filename class="directory">include</filename> sub-directory. For
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3010 packages which do not follow these conventions, typically simple ones
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3011 for which a complicated sub-directory hierarchy is undesirable, there
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3012 has to be an alternative way of specifying which header file or files
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3013 define the public interface. The &include-files; property provides
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3014 support for this.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3015 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3016 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3017 By default, if a package does not have an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3018 <filename class="directory">include</filename> subdirectory and it
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3019 does not have an &include-files; property then all files with a suffix
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3020 of <literal>.h</literal>, <literal>.hxx</literal>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3021 <literal>.inl</literal> or <literal>.inc</literal> will be treated as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3022 public header files. However some of these may be private files
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3023 containing implementation details. If there is an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3024 &include-files; property then only the files listed in that property
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3025 will be exported.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3026 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3027 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3028 If a package should not export any header files but does contain
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3029 private implementation headers, an &include-files; property with no
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3030 arguments should be used.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3031 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3032 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3033
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3034 <refsect1><title>Example</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3035 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3036 cdl_package <SOME_PACKAGE> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3037 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3038 include_dir <some directory>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3039 include_files interface.h
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3040 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3041
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3042 cdl_package <ANOTHER_PACKAGE> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3043 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3044 include_files
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3045 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3046 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3047 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3048
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3049 <refsect1><title>See Also</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3050 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3051 Property <link linkend="ref.include-dir">&include-dir;</link>, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3052 command <link linkend="ref.cdl-package">&cdl-package;</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3053 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3054 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3055
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3056 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3057
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3058 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3059 <!-- {{{ legal_values -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3060
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3061 <refentry id="ref.legal-values">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3062 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3063 <refentrytitle>&legal-values;</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3064 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3065
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3066 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3067 <refname>Property &legal-values;</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3068 <refpurpose>Impose constraints on the possible values for an option.</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3069 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3070
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3071 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3072 <synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3073 cdl_option <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3074 legal_values <list expression>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3075 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3076 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3077 </synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3078 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3079
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3080 <refsect1><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3081 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3082 Options with the <literal>data</literal> or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3083 <literal>booldata</literal> flavors can have an arbitrary sequence of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3084 characters as their data. In nearly all cases some restrictions have
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3085 to be imposed, for example the data should correspond to a number
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3086 within a certain range, or it should be one of a small number of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3087 constants. The &legal-values; property can be used to impose such
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3088 constraints. The arguments to the property should be a &CDL; list
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3089 expression, see <xref linkend="language.list-expression"> for the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3090 syntactic details. Common examples include:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3091 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3092 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3093 legal_values 0 to 0x7fff
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3094 legal_values 9600 19200 38400
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3095 legal_values { "RAM" "ROM" }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3096 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3097 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3098 The &legal-values; property can only be used for options with the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3099 <literal>data</literal> or <literal>booldata</literal> flavors, since
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3100 it makes little sense to further constrain the legal values of a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3101 boolean option. An option can have at most one &legal-values;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3102 property.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3103 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3104
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3105 <tip>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3106 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3107 If the first entry in a &legal-values; list expression is a negative
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3108 number, for example
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3109 <literal>legal_values -1 to 1</literal> then this can
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3110 be misinterpreted as an option instead of as part of the expression.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3111 Currently the &legal-values; property does not take any options, but
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3112 this may change in future. Option processing halts at the sequence
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3113 <literal>--</literal>, so the desired range can be expressed safely
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3114 using <literal>legal_values -- -1 to 1</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3115 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3116 </tip>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3117
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3118 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3119 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3120 Architectural HAL packages should provide constants which can be used
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3121 in &legal-values; list expressions. For example it should be possible
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3122 to specify a numeric range such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3123 <literal>0 to CYGARC_MAXINT</literal>, rather than
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3124 hard-wiring numbers such as <literal>0x7fffffff</literal> which may
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3125 not be valid on all targets. Current HAL packages do not define such
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3126 constants.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3127 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3128 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3129
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3130 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3131 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3132 The &legal-values; property is restricted mainly to numerical ranges
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3133 and simple enumerations, and cannot cope with more complicated data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3134 items. Future versions of the configuration system will provide
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3135 additional data validation facilities, for example a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3136 <literal>check_proc</literal> property which specifies a Tcl script
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3137 that can be used to perform the validation.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3138 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3139 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3140 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3141
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3142 <refsect1><title>Example</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3143 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3144 cdl_option CYGNUM_LIBC_TIME_STD_DEFAULT_OFFSET {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3145 display "Default Standard Time offset"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3146 flavor data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3147 legal_values -- -90000 to 90000
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3148 default_value -- 0
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3149 description "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3150 This option controls the offset from UTC in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3151 seconds when in local Standard Time. This
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3152 value can be positive or negative. It
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3153 can also be set at run time using the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3154 cyg_libc_time_setzoneoffsets() function."
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3155 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3156 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3157 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3158
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3159 <refsect1><title>See Also</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3160 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3161 Properties <link linkend="ref.calculated">&calculated;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3162 <link linkend="ref.default-value">&default-value;</link>, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3163 <link linkend="ref.flavor">&flavor;</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3164 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3165 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3166
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3167 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3168
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3169 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3170 <!-- {{{ library -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3171
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3172 <refentry id="ref.library">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3173 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3174 <refentrytitle>&library;</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3175 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3176
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3177 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3178 <refname>Property &library;</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3179 <refpurpose>Specify which library should contain the object files
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3180 generated by building this package.</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3181 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3182
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3183 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3184 <synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3185 cdl_package <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3186 library <library name>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3187 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3188 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3189 </synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3190 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3191
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3192 <refsect1><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3193 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3194 By default all object files that get built for all packages end up in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3195 a single library, <filename>libtarget.a</filename>. This makes things
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3196 easier for the typical application developer because it is only
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3197 necessary to link with a single library, rather than with separate
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3198 libraries for each package. It is possible to specify an alternative
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3199 library for specific files as an option to the &compile; and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3200 &make-object; properties, and there is one library <link
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3201 linkend="build"><filename>libextras.a</filename></link> which serves a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3202 specific purpose in the build system. The &library; property allows an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3203 alternative library to be specified for all the object files that will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3204 be generated for a given package.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3205 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3206 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3207 The use of the &library; property should be avoided, since it makes
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3208 things more difficult for application developers. The property is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3209 intended only for special cases, for example if there are legal
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3210 objections to mingling object files from different packages in a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3211 single library. It could also be used to work around name clash
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3212 problems if two packages happen to define an exported symbol with the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3213 same name, but any attempt to use multiple libraries in this way is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3214 error-prone and should be avoided.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3215 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3216 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3217 The &library; property takes a single argument, the name of a library,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3218 which should follow the standard naming convention of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3219 <literal>lib<something>.a</literal>. A &library; property can
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3220 only occur in the body of a &cdl-package; command and applies to all
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3221 object files generated for that package (except where explicitly
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3222 overwritten with a <literal>-library=</literal> option to one of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3223 build-related properties). A &cdl-package; body can contain at most
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3224 one &library; property.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3225 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3226 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3227
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3228 <refsect1><title>Example</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3229 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3230 cdl_package <SOME_PACKAGE> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3231 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3232 library libSomePackage.a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3233 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3234 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3235 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3236
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3237 <refsect1><title>See Also</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3238 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3239 Properties <link linkend="ref.compile">&compile;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3240 <link linkend="ref.make">&make;</link>, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3241 <link linkend="ref.make-object">&make-object;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3242 command <link linkend="ref.cdl-package">&cdl-package;</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3243 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3244 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3245
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3246 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3247
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3248 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3249 <!-- {{{ make -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3250
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3251 <refentry id="ref.make">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3252 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3253 <refentrytitle>&make;</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3254 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3255
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3256 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3257 <refname>Property &make;</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3258 <refpurpose>Define an additional custom build step associated with an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3259 option, resulting in a target that should not go directly into a library.</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3260 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3261
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3262 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3263 <synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3264 cdl_option <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3265 make [-priority=<pri>] {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3266 <custom build step>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3267 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3268 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3269 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3270 </synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3271 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3272
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3273 <refsect1><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3274 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3275 When building an &eCos; configuration the primary target is a single
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3276 library, <filename>libtarget.a</filename>. In some cases it is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3277 necessary to build some additional targets. For example architectural
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3278 HAL packages typically build a linker script and some start-up code.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3279 Such additional targets can be specified by a &make; property. Any
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3280 option can have one or more &make; properties, although typically such
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3281 properties only occur in the body of a &cdl-package; command.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3282 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3283 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3284 The &make; property takes a single argument, which resembles a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3285 makefile rule: it consists of a target, a list of dependencies, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3286 one or more commands that should be executed. However the argument is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3287 not a makefile fragment, and custom build steps may get executed in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3288 build environments that do not involve make. For full details of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3289 custom build steps see <xref linkend="build.custom">.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3290 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3291 <warning>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3292 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3293 The exact syntax and limitations of custom build steps have not yet
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3294 been finalized, and are subject to change in future versions of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3295 configuration tools.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3296 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3297 </warning>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3298 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3299 The &make; property takes an optional priority argument indicating the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3300 order in which build steps take place. This priority complements the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3301 dependency list, and avoids problems with packages needing to know
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3302 details of custom build steps in other packages (which may change
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3303 between releases). The defined order is:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3304 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3305 <variablelist termlength=12>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3306
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3307 <varlistentry><term>Priority 0</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3308 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3309 The header files exported by the current set of packages are copied
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3310 to the appropriate places in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3311 <filename class="directory">include</filename> subdirectory of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3312 install tree. Any unnecessary copies are avoided, to prevent rebuilds
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3313 of package and application source modules caused by header file dependencies.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3314 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3315 <note><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3316 A possible future enhancement of the build system may result in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3317 build and install trees being updated automatically if there has been
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3318 a change to the <filename>ecos.ecc</filename> configuration savefile.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3319 </para></note></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3320 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3321
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3322 <varlistentry><term>Priority 100</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3323 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3324 All files specified in &compile; properties will get built, producing
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3325 the corresponding object files. In addition any custom build steps
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3326 defined by &make-object; properties get executed, unless there is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3327 a <literal>-priority=</literal> option.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3328 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3329 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3330
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3331 <varlistentry><term>Priority 200</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3332 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3333 The libraries now get built using the appropriate object files.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3334 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3335 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3336
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3337 <varlistentry><term>Priority 300</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3338 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3339 Any custom build steps specified by &make; properties now get
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3340 executed, unless the priority for a particular build step is changed
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3341 from its default.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3342 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3343 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3344 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3345
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3346 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3347 For example, if a custom build step needs to take place before any of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3348 the normal source files get compiled then it should be given a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3349 priority somewhere between 0 and 100. If a custom build step involves
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3350 post-processing an object file prior to its incorporation into a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3351 library then a priority between 100 and 200 should be used.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3352 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3353
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3354 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3355
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3356 <refsect1><title>Example</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3357 <programlisting width=88>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3358 cdl_package CYGPKG_HAL_MN10300_AM33 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3359 display "MN10300 AM33 variant"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3360 parent CYGPKG_HAL_MN10300
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3361 implements CYGINT_HAL_MN10300_VARIANT
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3362 hardware
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3363 include_dir cyg/hal
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3364 define_header hal_mn10300_am33.h
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3365 description "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3366 The MN10300 AM33 variant HAL package provides generic
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3367 support for this processor architecture. It is also
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3368 necessary to select a specific target platform HAL
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3369 package."
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3370
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3371 make {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3372 <PREFIX>/lib/target.ld: <PACKAGE>/src/mn10300_am33.ld
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3373 $(CC) -E -P -Wp,-MD,target.tmp -DEXTRAS=1 -xc $(INCLUDE_PATH) $(CFLAGS) -o $@ $<
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3374 @echo $@ ": \\" > $(notdir $@).deps
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3375 @tail +2 target.tmp >> $(notdir $@).deps
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3376 @echo >> $(notdir $@).deps
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3377 @rm target.tmp
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3378 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3379 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3380 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3381 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3382
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3383 <refsect1><title>See Also</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3384 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3385 Properties <link linkend="ref.compile">compile</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3386 <link linkend="ref.make-object">make_object</link> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3387 <link linkend="ref.library">library</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3388 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3389 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3390
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3391 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3392
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3393 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3394 <!-- {{{ make_object -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3395
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3396 <refentry id="ref.make-object">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3397 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3398 <refentrytitle>&make-object;</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3399 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3400
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3401 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3402 <refname>Property &make-object;</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3403 <refpurpose>Define a custom build step, resulting in an object file
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3404 that should go into a library.</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3405 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3406
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3407 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3408 <synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3409 cdl_option <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3410 make_object [-library=<library>] [-priority=<pri>] {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3411 <custom build step>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3412 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3413 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3414 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3415 </synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3416 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3417
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3418 <refsect1><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3419 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3420 When building an &eCos; configuration the primary target is a single
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3421 library, <filename>libtarget.a</filename>. Most of the object files
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3422 which go into this library will be generated as a result of &compile;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3423 properties. Occasionally it may be necessary to have special build
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3424 steps for a given object file, and this can be achieved with a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3425 &make-object; property. The use of this property should be avoided
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3426 whenever possible because it greatly increases the risk of portability
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3427 problems, both on the host side because of possible problems with the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3428 tools, and on the target side because a custom build step may not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3429 allow adequately for the wide variety of architectures supported by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3430 &eCos;.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3431 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3432 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3433 The &make-object; property takes a single argument, which resembles a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3434 makefile rule: it consists of a target, a list of dependencies, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3435 one or more commands that should be executed. The target should be an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3436 object file. However the &make-object; argument is not a makefile
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3437 fragment, and custom build steps may get executed in build
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3438 environments that do not involve make. For full details of custom
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3439 build steps see <xref linkend="build.custom">.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3440 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3441 <warning>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3442 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3443 The exact syntax and limitations of custom build steps have not yet
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3444 been finalized, and may change in future versions of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3445 configuration tools.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3446 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3447 </warning>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3448 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3449 The &make-object; property takes an optional library argument. If no
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3450 library is specified then the default library for the current package
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3451 will be used, which will be <filename>libtarget.a</filename> unless
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3452 the &cdl-package; command contains a &library; property.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3453 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3454 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3455 The &make-object; property also takes an optional priority argument
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3456 indicating the order in which build steps take place. This priority
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3457 complements the dependency list, and avoids problems with packages
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3458 needing to know details of custom build steps in other packages (which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3459 may change between releases). The defined order is:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3460 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3461 <variablelist termlength=12>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3462
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3463 <varlistentry><term>Priority 0</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3464 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3465 The header files exported by the current set of packages are copied
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3466 to the appropriate places in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3467 <filename class="directory">include</filename> subdirectory of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3468 install tree. Any unnecessary copies are avoided, to prevent rebuilds
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3469 of package and application source modules caused by header file dependencies.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3470 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3471 <note><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3472 A possible future enhancement of the build system may result in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3473 build and install trees being updated automatically if there has been
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3474 a change to the <filename>ecos.ecc</filename> configuration savefile.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3475 </para></note></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3476 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3477
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3478 <varlistentry><term>Priority 100</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3479 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3480 All files specified in &compile; properties will get built, producing
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3481 the corresponding object files. In addition any custom build steps
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3482 defined by &make-object; properties get executed, unless there is a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3483 <literal>-priority=</literal> option.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3484 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3485 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3486
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3487 <varlistentry><term>Priority 200</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3488 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3489 The libraries now get built using the appropriate object files.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3490 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3491 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3492
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3493 <varlistentry><term>Priority 300</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3494 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3495 Any custom build steps specified by &make; properties now get
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3496 executed, unless the priority for a particular build step is changed
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3497 from its default.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3498 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3499 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3500 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3501
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3502 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3503 For example, if a custom build step needs to take place before any of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3504 the normal source files get compiled then it should be given a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3505 priority somewhere between 0 and 100. If a custom build step involves
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3506 post-processing an object file prior to its incorporation into a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3507 library then a priority between 100 and 200 should be used. It is not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3508 sensible to have a priority above 200, since that would imply building
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3509 an additional object file for a library that has already been created.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3510 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3511 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3512
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3513 <refsect1><title>Example</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3514 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3515 cdl_option XXX {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3516 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3517 make_object {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3518 parser.o: parser.y
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3519 yacc $<
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3520 $(CC) $(CFLAGS) -o $@ y.tab.c
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3521 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3522 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3523 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3524 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3525
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3526 <refsect1><title>See Also</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3527 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3528 Properties <link linkend="ref.compile">compile</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3529 <link linkend="ref.make">make</link> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3530 <link linkend="ref.library">library</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3531 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3532 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3533
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3534 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3535
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3536 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3537 <!-- {{{ no_define -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3538
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3539 <refentry id="ref.no-define">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3540 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3541 <refentrytitle>&no-define;</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3542 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3543
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3544 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3545 <refname>Property &no-define;</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3546 <refpurpose>Suppress the normal generation of a preprocessor
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3547 <literal>#define</literal> symbol in a configuration header file.</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3548 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3549
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3550 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3551 <synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3552 cdl_option <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3553 no_define
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3554 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3555 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3556 </synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3557 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3558
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3559 <refsect1><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3560 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3561 By default all active and enabled properties result in either one or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3562 two <literal>#define'd</literal> symbols in the package's
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3563 configuration header file, and this is one of the main ways in which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3564 options can affect packages at build-time. It is possible to suppress
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3565 the default <literal>#define's</literal> by specifying a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3566 &no-define; property in the body of an option or other &CDL; entity.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3567 This property takes no arguments and should occur only once in a given
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3568 body.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3569 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3570 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3571 The &no-define; property is frequently used in conjunction with one of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3572 the other header-file related properties such as &define;. If one of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3573 the other properties is used to export the required information to a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3574 configuration header file then often there is little point in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3575 exporting the default <literal>#define</literal> as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3576 well &mdash  in fact there could be a name clash. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3577 &no-define; property can also be useful if the sole purpose of an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3578 option is to affect which files get built, and the default
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3579 <literal>#define</literal> would never get tested in any source code.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3580 However in such cases the default <literal>#define</literal> is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3581 mostly harmless and there is little to be gained by suppressing it.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3582 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3583
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3584 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3585
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3586 <refsect1><title>Example</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3587 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3588 cdl_component CYG_HAL_STARTUP {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3589 display "Startup type"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3590 flavor data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3591 legal_values { "RAM" "ROM" }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3592 default_value {"RAM"}
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3593 no_define
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3594 define -file system.h CYG_HAL_STARTUP
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3595 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3596 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3597 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3598 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3599
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3600 <refsect1><title>See Also</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3601 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3602 Properties <link linkend="ref.define">&define;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3603 <link linkend="ref.define-format">&define-format;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3604 <link linkend="ref.define-header">&define-header;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3605 <link linkend="ref.define-proc">&define-proc;</link> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3606 <link linkend="ref.if-define">&if-define;</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3607 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3608 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3609
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3610 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3611
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3612 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3613 <!-- {{{ parent -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3614
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3615 <refentry id="ref.parent">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3616 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3617 <refentrytitle>&parent;</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3618 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3619
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3620 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3621 <refname>Property &parent;</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3622 <refpurpose>Control the location of an option in the configuration hierarchy.</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3623 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3624
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3625 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3626 <synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3627 cdl_option <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3628 parent <component or package>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3629 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3630 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3631 </synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3632 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3633
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3634 <refsect1><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3635 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3636 Configuration options live in a hierarchy of packages and components.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3637 By default a given option's position in the hierarchy is a simple
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3638 consequence of its position within the CDL scripts. Packages are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3639 generally placed at the top-level of the configuration. Any components
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3640 or options that are defined at the same level as the &cdl-package;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3641 command in a package's top-level CDL script are placed immediately
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3642 below that package in the hierarchy. Any options or components that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3643 are defined in the body of a &cdl-package; or &cdl-component; command,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3644 or that are read in as a result of processing a component's &script;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3645 property, will be placed immediately below that package or component
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3646 in the hierarchy.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3647 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3648 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3649 In some circumstances it is useful to specify an alternative position
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3650 in the hierarchy for a given option. For example it is often
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3651 convenient to re-parent device driver packages below
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3652 <varname>CYGPKG_IO</varname> in the configuration hierarchy, thus
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3653 reducing the number of packages at the top level of the hierarchy and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3654 making navigation easier. The &parent; property can be used to achieve
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3655 this.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3656 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3657 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3658 The &parent; property takes a single argument, which should be the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3659 name of a package or component. The body of a &cdl-option; or other
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3660 CDL entity can contain at most one &parent; property.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3661 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3662 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3663 Although the &parent; property affects an option's position in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3664 overall hierarchy and hence whether or not that option is active, a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3665 re-parented option still belongs to the package that defines it. By
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3666 default any <literal>#define's</literal> will be exported to that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3667 package's configuration header file. Any &compile; properties can only
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3668 reference source files present in that package, and it is not directly
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3669 possible to cause some file in another package to be built by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3670 re-parenting.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3671 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3672 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3673 As a special case, if an empty string is specified for the parent then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3674 the option is placed at the top of the hierarchy, ahead of any
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3675 packages which are not explicitly re-parented in this way. This
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3676 facility is useful for configuration options such as global
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3677 preferences and default compiler flags.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3678 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3679
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3680 <tip>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3681 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3682 If an option is re-parented somewhere below another package and that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3683 other package is not actually loaded, the option is an orphan and its
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3684 active/inactive state is undefined. In such cases it is a good idea
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3685 for the owning package to require the presence of the other one.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3686 Unfortunately this technique does not work if a package as a whole is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3687 reparented below another one that has not been loaded: the package is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3688 orphaned so it may be automatically inactive, and hence any &requires;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3689 properties would have no effect.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3690 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3691 </tip>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3692
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3693 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3694
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3695 <refsect1><title>Example</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3696 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3697 cdl_package CYGPKG_HAL_I386 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3698 display "i386 architecture"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3699 parent CYGPKG_HAL
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3700 hardware
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3701 include_dir cyg/hal
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3702 define_header hal_i386.h
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3703 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3704 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3705
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3706 cdl_component CYGBLD_GLOBAL_OPTIONS {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3707 display "Global build options"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3708 parent ""
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3709 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3710 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3711 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3712 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3713
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3714 <refsect1><title>See Also</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3715 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3716 Property <link linkend="ref.script">&script;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3717 commands <link linkend="ref.cdl-component">&cdl-component;</link> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3718 <link linkend="ref.cdl-package">&cdl-package;</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3719 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3720 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3721
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3722 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3723
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3724 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3725 <!-- {{{ requires -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3726
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3727 <refentry id="ref.requires">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3728 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3729 <refentrytitle>&requires;</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3730 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3731
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3732 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3733 <refname>Property &requires;</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3734 <refpurpose>List constraints that the configuration should satisfy if
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3735 a given option is active and enabled..</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3736 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3737
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3738 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3739 <synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3740 cdl_option <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3741 requires <goal expression>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3742 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3743 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3744 </synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3745 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3746
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3747 <refsect1><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3748 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3749 Configuration options are not independent. For example the C library
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3750 can provide thread-safe implementations of certain functions, but only
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3751 if the kernel is present, if the kernel provides multi-threading, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3752 if the kernel options related to per-thread data are enabled. It is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3753 possible to express such constraints using &requires; properties.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3754 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3755 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3756 The arguments to a &requires; property should constitute a goal
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3757 expression, as described in <xref linkend="language.list-expression">.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3758 Most goal expressions are relatively simple because the constraints
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3759 being described are simple, but complicated expressions can be used
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3760 when necessary. The body of an option or other CDL entity can contain
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3761 any number of &requires; constraints. If the option is active and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3762 enabled then all these constraints should be satisfied, and any goal
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3763 expressions which evaluate to <literal>0</literal> will result in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3764 conflicts being raised. It is possible for users to ignore such
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3765 conflicts and attempt to build the current configuration anyway, but
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3766 there is no guarantee that anything will work. If an option is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3767 inactive or disabled then its &requires; constraints will be ignored.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3768 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3769 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3770 The configuration system contains an inference engine which can
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3771 resolve many types of conflicts automatically. For example, if option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3772 <literal>A</literal> is enabled and requires an option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3773 <literal>B</literal> that is currently disabled then the inference
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3774 engine may attempt to resolve the conflict by enabling
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3775 <literal>B</literal>. However this will not always be possible, for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3776 example there may be other constraints in the configuration which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3777 force <literal>B</literal> to be disabled at present, in which case
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3778 user intervention is required.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3779 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3780 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3781
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3782 <refsect1><title>Example</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3783 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3784 cdl_component CYGPKG_IO_SERIAL_POWERPC_COGENT_SERIAL_A {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3785 display "Cogent PowerPC serial port A driver"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3786 flavor bool
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3787 default_value 0
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3788 requires (CYGIMP_KERNEL_INTERRUPTS_CHAIN \|\| \
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3789 !CYGPKG_IO_SERIAL_POWERPC_COGENT_SERIAL_B)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3790 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3791 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3792 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3793 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3794
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3795 <refsect1><title>See Also</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3796 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3797 Property <link linkend="ref.active-if">&active-if;</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3798 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3799 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3800
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3801 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3802
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3803 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3804 <!-- {{{ script -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3805
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3806 <refentry id="ref.script">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3807 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3808 <refentrytitle>&script;</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3809 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3810
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3811 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3812 <refname>Property &script;</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3813 <refpurpose>Include additional configuration information from another
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3814 CDL script.</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3815 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3816
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3817 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3818 <synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3819 cdl_component <name> {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3820 script <filename>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3821 …
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3822 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3823 </synopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3824 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3825
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3826 <refsect1><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3827 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3828 It is possible to define all the configuration options and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3829 sub-components for a given package in a single CDL script, either by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3830 nesting them in the appropriate command bodies, by extensive use of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3831 the &parent; property, or by some combination of these two. However
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3832 for large packages this is inconvenient and it is better to split the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3833 raw configuration data over several different files. The &script;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3834 property can be used to achieve this. It takes a single filename as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3835 argument. If the package follows the <link
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3836 linkend="package.hierarchy">directory layout conventions</link> then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3837 the configuration tools will look for the specified file in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3838 <filename class="directory">cdl</filename> sub-directory of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3839 package, otherwise it will look for the file relative to the package's
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3840 top-level directory.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3841 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3842 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3843 The &script; property can only occur in the body of a &cdl-component
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3844 command, and only one &script; property per body is allowed.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3845 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3846 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3847
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3848 <refsect1><title>Example</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3849 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3850 cdl_component CYGPKG_UITRON_TASKS {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3851 display "Tasks"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3852 flavor none
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3853 description "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3854 uITRON Tasks are the basic blocks of multi-tasking
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3855 in the uITRON world; they are threads or lightweight
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3856 processes, sharing the address space and the CPU.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3857 They communicate using the primitives outlined above.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3858 Each has a stack, an entry point (a C or C++ function),
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3859 and (where appropriate) a scheduling priority."
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3860
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3861 script tasks.cdl
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3862 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3863 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3864 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3865
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3866 <refsect1><title>See Also</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3867 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3868 Command <link linkend="ref.cdl-component">&cdl-component;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3869 and property <link linkend="ref.parent">&parent;</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3870 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3871 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3872
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3873 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3874
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3875 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3876
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST jlarmour parents: diff changeset	3877 </chapter>

Mercurial > flash_v2

annotate host/libcdl/doc/reference.sgml @ 334:c9cbf5dfb306