Mercurial > flash_v2

annotate host/libcdl/doc/language.sgml @ 210:d2c90368aeef

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Merge from eCos master repository on 2002-05-23-21:39:14-BST
author jlarmour
date Thu, 23 May 2002 22:59:51 +0000
parents
children c9cbf5dfb306
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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 <!-- language.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 CDL language. -->
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 <!-- =============================================================== -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
13 <!-- Copyright (C) 2000, 2001 Red Hat, Inc. -->
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 substantively modified versions of this -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
20 <!-- document is prohibited without the explicit permission of the -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
21 <!-- copyright holder. -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
22 <!-- 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
23 <!-- 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
24 <!-- permission obtained from the copyright holder -->
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 <!-- -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
27 <!-- ####COPYRIGHTEND#### -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
28 <!-- =============================================================== -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
29 <!-- #####DESCRIPTIONBEGIN#### -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
30 <!-- -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
31 <!-- Author(s): bartv -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
32 <!-- Contact(s): bartv -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
33 <!-- Date: 2000/02/06 -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
34 <!-- Version: 0.01 -->
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 <!-- ####DESCRIPTIONEND#### -->
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
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
39 <!-- }}} -->
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 <chapter id="language">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
42 <title>The CDL Language</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
43
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
44 <!-- {{{ Introit -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
45
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 The &CDL; language is a key part of the &eCos; component framework.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
48 All packages must come with at least one &CDL; script, to describe
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
49 that package to the framework. The information in that script includes
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
50 details of all the configuration options and how to build the package.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
51 Implementing a new component or turning some existing code into an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
52 &eCos; component always involves writing corresponding &CDL;. This
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
53 chapter provides a description of the &CDL; language. Detailed
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
54 information on specific parts of the language can be found in <xref
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
55 linkend="reference">.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
56 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
57
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
58 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
59 <!-- {{{ Language overview -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
60
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
61 <sect1 id="language.overview">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
62 <title>Language Overview</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
63 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
64 A very simple &CDL; script would look like this:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
65 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
66 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
67 cdl_package CYGPKG_ERROR {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
68 display "Common error code support"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
69 compile strerror.cxx
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
70 include_dir cyg/error
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
71 description "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
72 This package contains the common list of error and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
73 status codes. It is held centrally to allow
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
74 packages to interchange error codes and status
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
75 codes in a common way, rather than each package
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
76 having its own conventions for error/status
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
77 reporting. The error codes are modelled on the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
78 POSIX style naming e.g. EINVAL etc. This package
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
79 also provides the standard strerror() function to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
80 convert error codes to textual representation."
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
81 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
82 </programlisting>
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 This describes a single package, the error code package, which does
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
85 not have any sub-components or configuration options. The package has
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
86 an internal name, <varname>CYGPKG_ERROR</varname>, which can be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
87 referenced in other &CDL; scripts using e.g.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
88 <literal>requires&nbsp;CYGPKG_ERROR</literal>. There will also be a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
89 <literal>#define</literal> for this symbol in a configuration header
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
90 file. In addition to the package name, this script provides a number
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
91 of properties for the package as a whole. The &display; property
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
92 provides a short description. The &description; property involves a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
93 rather longer one, for when users need a bit more information. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
94 &compile; and &include-dir; properties list the consequences of this
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
95 package at build-time. The package appears to lack any on-line
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
96 documentation.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
97 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
98 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
99 Packages could be even simpler than this. If the package only provides
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
100 an interface and there are no files to be compiled then there is no
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
101 need for a &compile; property. Alternatively if there are no exported
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
102 header files, or if the exported header files should go to the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
103 top-level of the <filename
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
104 class="directory">install/include</filename> directory, then there is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
105 no need for an &include-dir; property. Strictly speaking the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
106 &description; and &display; properties are optional as well, although
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
107 application developers would not appreciate the resulting lack of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
108 information about what the package is supposed to do.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
109 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
110 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
111 However many packages tend to be a bit more complicated than the error
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
112 package, containing various sub-components and configuration options.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
113 These are also defined in the &CDL; scripts and in much the same way
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
114 as the package. For example, the following excerpt comes from the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
115 infrastructure package:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
116 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
117 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
118 cdl_component CYGDBG_INFRA_DEBUG_TRACE_ASSERT_BUFFER {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
119 display "Buffered tracing"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
120 default_value 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
121 active_if CYGDBG_USE_TRACING
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
122 description "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
123 An output module which buffers output from tracing and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
124 assertion events. The stored messages are output when an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
125 assert fires, or CYG_TRACE_PRINT() (defined in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
126 &lt;cyg/infra/cyg_trac.h&gt;) is called. Of course, there will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
127 only be stored messages if tracing per se (CYGDBG_USE_TRACING)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
128 is enabled above."
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
129
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
130 cdl_option CYGDBG_INFRA_DEBUG_TRACE_BUFFER_SIZE {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
131 display "Trace buffer size"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
132 flavor data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
133 default_value 32
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
134 legal_values 5 to 65535
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
135 description "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
136 The size of the trace buffer. This counts the number of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
137 trace records stored. When the buffer fills it either
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
138 wraps, stops recording, or generates output."
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
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
141 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
142 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
143 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
144 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
145 Like a &cdl-package;, a &cdl-component; has a name and a body. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
146 body contains various properties for that component, and may also
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
147 contain sub-components or options. Similarly a &cdl-option; has a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
148 name and a body of properties. This example lists a number of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
149 new properties: &default-value;, &active-if;, &flavor; and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
150 &legal-values;. The meaning of most of these should be fairly obvious.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
151 The next sections describe the various &CDL; commands and properties.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
152 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
153 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
154 There is one additional and very important point: &CDL; is not a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
155 completely new language; instead it is implemented as an extension of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
156 the existing &Tcl; scripting language. The syntax of a &CDL; script is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
157 &Tcl; syntax, which is described below. In addition some of the more
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
158 advanced facilities of &CDL; involve embedded fragments of &Tcl; code,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
159 for example there is a &define-proc; property which specifies some
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
160 code that needs to be executed when the component framework generates
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
161 the configuration header files.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
162 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
163
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
164 </sect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
165
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 <!-- {{{ CDL commands -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
168
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
169 <sect1 id="language.commands">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
170 <title>CDL Commands</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
171 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
172 There are four &CDL;-related commands which can occur at the top-level
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
173 of a &CDL; script: &cdl-package;, &cdl-component;, &cdl-option; and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
174 &cdl-interface;. These correspond to the basic building blocks of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
175 language (CDL interfaces are described in <xref
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
176 linkend="language.interface">). All of these take the same basic form:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
177 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
178 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
179 cdl_package &lt;name&gt; {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
180 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
181 }
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 cdl_component &lt;name&gt; {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
184 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
185 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
186
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
187 cdl_option &lt;name&gt; {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
188 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
189 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
190
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
191 cdl_interface &lt;name&gt; {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
192 &hellip;
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 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
195 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
196 The command is followed by a name and by a body of properties, the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
197 latter enclosed in braces. Packages and components can contain other
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
198 entities, so the &cdl-package; and &cdl-component; can also have
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
199 nested commands in their bodies. All names must be unique within a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
200 given configuration. If say the C library package and a TCP/IP stack
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
201 both defined an option with the same name then it would not be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
202 possible to load both of them into a single configuration. There is a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
203 <link linkend="language.naming">naming convention</link> which should
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
204 make accidental name clashes very unlikely.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
205 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
206 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
207 It is possible for two packages to use the same name if there are no
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
208 reasonable circumstances under which both packages could be loaded at
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
209 the same time. One example would be architectural HAL packages: a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
210 given &eCos; configuration can be used on only one processor, so the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
211 architectural HAL packages <varname>CYGPKG_HAL_ARM</varname> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
212 <varname>CYGPKG_HAL_I386</varname> can re-use option names; in fact
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
213 in some cases they are expected to.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
214 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
215 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
216 Each package has one top-level &CDL; script, which is specified in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
217 packages <link
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
218 linkend="language.database"><database>ecos.db</database> database
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
219 entry</link>. Typically the name of this top-level script is related to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
220 the package, so the kernel package uses
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
221 <filename>kernel.cdl</filename>, but this is just a convention. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
222 first command in the top-level script should be &cdl-package;, and the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
223 name used should be the same as in the <database>ecos.db</database>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
224 database. There should be only one &cdl-package; command per package.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
225 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
226 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
227 The various &CDL; entities live in a hierarchy. For example the kernel
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
228 package contains a scheduling component, a synchronization primitives
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
229 component, and a number of others. The synchronization component
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
230 contains various options such as whether or not mutex priority
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
231 inheritance is enabled. There is no upper bound on how far components
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
232 can be nested, but it is rarely necessary to go more than three or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
233 four levels deeper than the package level. Since the naming convention
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
234 incorporates bits of the hierarchy, this has the added advantage of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
235 keeping the names down to a more manageable size.
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 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
238 The hierarchy serves two purposes. It allows options to be controlled
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
239 en masse, so disabling a component automatically disables all the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
240 options below it in the hierarchy. It also permits a much simpler
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
241 representation of the configuration in the graphical configuration
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
242 tool, facilitating navigation and modification.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
243 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
244 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
245 By default a package is placed at the top-level of the hierarchy, but
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
246 it is possible to override this using a &parent; property. For example
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
247 an architectural HAL package such as <varname>CYGPKG_HAL_SH</varname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
248 typically re-parents itself below <varname>CYGPKG_HAL</varname>, and a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
249 platform HAL package would then re-parent itself below the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
250 architectural HAL. This makes it a little bit easier for users to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
251 navigate around the hierarchy. Components, options and interfaces can
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
252 also be re-parented, but this is less common.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
253 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
254 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
255 All components, options and interfaces that are defined directly in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
256 the top-level script will be placed below the package in the hierarchy.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
257 Alternatively they can be nested in the body of the &cdl-package;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
258 command. The following two script fragments are equivalent:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
259 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
260 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
261 cdl_package CYGPKG_LIBC {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
262 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
263 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
264
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
265 cdl_component CYGPKG_LIBC_STRING {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
266 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
267 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
268
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
269 cdl_option CYGPKG_LIBC_CTYPE_INLINES {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
270 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
271 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
272 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
273 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
274 and:
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 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
277 cdl_package CYGPKG_LIBC {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
278 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
279
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
280 cdl_component CYGPKG_LIBC_STRING {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
281 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
282 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
283
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
284 cdl_option CYGPKG_LIBC_CTYPE_INLINES {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
285 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
286 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
287 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
288 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
289 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
290 If a script defines options both inside and outside the body of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
291 &cdl-package; then the ones inside will be processed first. Language
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
292 purists may argue that it would have been better if all contained
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
293 options and components had to go into the body, but in practice it is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
294 often convenient to be able to skip this level of nesting and the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
295 resulting behavior is still well-defined.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
296 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
297 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
298 Components can also contain options and other &CDL; entities, in fact
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
299 that is what distinguishes them from options. These can be defined in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
300 the body of the &cdl-component; command:
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 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
303 cdl_component CYGPKG_LIBC_STDIO {
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 cdl_component CYGPKG_LIBC_STDIO_FLOATING_POINT {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
306 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
307 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
308
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
309 cdl_option CYGSEM_LIBC_STDIO_THREAD_SAFE_STREAMS {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
310 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
311 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
312 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
313 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
314 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
315 Nesting options inside the bodies of components like this is fine for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
316 simple packages with only a limited number of configuration options,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
317 but it becomes unsatisfactory as the number of options increases.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
318 Instead it is possible to split the &CDL; data into multiple &CDL;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
319 scripts, on a per-component basis. The &script; property should be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
320 used for this. For example, in the case of the C library all
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
321 stdio-related configuration options could be put into
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
322 <filename>stdio.cdl</filename>, and the top-level CDL script
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
323 <filename>libc.cdl</filename> would contain the following:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
324 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
325 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
326 cdl_package CYGPKG_LIBC {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
327 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
328
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
329 cdl_component CYGPKG_LIBC_STDIO {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
330 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
331 script stdio.cdl
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 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
334 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
335 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
336 The <varname>CYGPKG_LIBC_STDIO_FLOATING_POINT</varname> component and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
337 the <varname>CYGSEM_LIBC_STDIO_THREAD_SAFE_STREAMS</varname> option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
338 can then be placed at the top-level of <filename>stdio.cdl</filename>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
339 It is possible to have some options nested in the body of a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
340 &cdl-component; command and other options in a separate file accessed
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
341 by the &script; property. In such a case the nested options would be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
342 processed first, and then the other script would be read in. A script
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
343 specified by a &script; property should only define new options,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
344 components or interfaces: it should not contain any additional
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
345 properties for the current component.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
346 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
347 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
348 It is possible for a component's &CDL; script to have a sub-component
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
349 which also has a &script; property, and so on. In practice excessive
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
350 nesting like this is rarely useful. It is also possible to ignore the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
351 &CDL; language support for constructing hierarchies automatically and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
352 use the &parent; property explicitly for every single option and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
353 component. Again this is not generally useful.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
354 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
355 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
356 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
357 At the time of writing interfaces cannot act as containers. This may
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
358 change in a future version of the component framework. If the change
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
359 is made then interfaces would support the &script; property, just like
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
360 components.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
361 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
362 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
363
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
364 </sect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
365
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 <!-- {{{ CDL properties -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
368
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
369 <!-- {{{ Introit -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
370
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
371 <sect1 id="language.properties">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
372 <title>CDL Properties</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
373 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
374 Each package, component, option, and interface has a body of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
375 properties, which provide the component framework with information
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
376 about how to handle each option. For example there is a property for a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
377 descriptive text message which can be displayed to a user who is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
378 trying to figure out just what effect manipulating the option would
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
379 have on the target application. There is another property for the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
380 default value, for example whether a particular option should be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
381 enabled or disabled by default.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
382 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
383 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
384 All of the properties are optional, it is legal to define a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
385 configuration option which has an empty body. However some properties
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
386 are more optional than others: users will not appreciate having to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
387 manipulate an option if they are not given any sort of description or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
388 documentation. Other properties are intended only for very specific
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
389 purposes, for example &make-object; and &include-files;, and are used
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
390 only rarely.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
391 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
392 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
393 Because different properties serve very different purposes, their
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
394 syntax is not as uniform as the top-level commands. Some properties
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
395 take no arguments at all. Other properties take a single argument such
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
396 as a description string, or a list of arguments such as a &compile;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
397 property which specifies the file or files that should be compiled if
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
398 a given option is active and enabled. The &define-proc; property takes
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
399 as argument a snippet of &Tcl; code. The &active-if;, &calculated;,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
400 &default-value;, &legal-values; and &requires; properties take various
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
401 expressions. Additional properties may be defined in future which take
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
402 new kinds of arguments.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
403 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
404 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
405 All property parsing code supports options for every property,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
406 although at present the majority of properties do not yet take any
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
407 options. Any initial arguments that begin with a hyphen character
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
408 <literal>-</literal> will be interpreted as an option, for example:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
409 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
410 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
411 cdl_package CYGPKG_HAL_ARM {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
412 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
413 make -priority 1 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
414 &hellip;
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 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
417 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
418 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
419 If the option involves additional data, as for the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
420 <literal>-priority</literal> example above, then this can be written
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
421 as either <literal>-priority=1</literal> or as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
422 <literal>-priority&nbsp;1</literal>. On occasion the option parsing
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
423 code can get in the way, for example:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
424 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
425 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
426 cdl_option CYGNUM_LIBC_TIME_DST_DEFAULT_STATE {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
427 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
428 legal_values -1 to 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
429 default_value -1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
430 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
431 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
432 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
433 Neither the &legal-values; nor the &default-value; property will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
434 accept <literal>-1</literal> as a valid option, so this will result in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
435 syntax errors when the &CDL; script is read in by the component
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
436 framework. To avoid problems, the option parsing code will recognize
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
437 the string <literal>--</literal> and will not attempt to interpret any
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
438 subsequent arguments. Hence this option should be written as:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
439 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
440 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
441 cdl_option CYGNUM_LIBC_TIME_DST_DEFAULT_STATE {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
442 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
443 legal_values -- -1 to 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
444 default_value -- -1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
445 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
446 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
447 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
448 The property parsing code involves a recursive invocation of the Tcl
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
449 interpreter that is used to parse the top-level commands. This means
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
450 that some characters in the body of an option will be treated
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
451 specially. The <literal>#</literal> character can be used for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
452 comments. The backslash character <literal>\</literal>, the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
453 dollar character <literal>$</literal>, square brackets
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
454 <literal>[</literal> and <literal>]</literal>, braces
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
455 <literal>{</literal> and <literal>}</literal>, and the quote character
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
456 <literal>"</literal> may all receive special treatment. Most of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
457 time this is not a problem because these characters are not useful for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
458 most properties. On occasion having a &Tcl; interpreter around
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
459 performing the parser can be very powerful. For more details of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
460 how the presence of a &Tcl; interpreter can affect &CDL; scripts,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
461 see <xref linkend="language.tcl">.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
462 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
463 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
464 Many of the properties can be used in any of &cdl-package;,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
465 &cdl-component;, &cdl-option; or &cdl-interface;. Other properties are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
466 more specific. The &script; property is only relevant to components.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
467 The &define-header;, &hardware;, &include-dir;, &include-files;, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
468 &library; properties apply to a package as a whole, so can only occur
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
469 in the body of a &cdl-package; command. The &calculated;,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
470 &default-value;, &legal-values; and &flavor; properties are not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
471 relevant to packages, as will be explained later. The &calculated; and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
472 &default-value; properties are also not relevant to interfaces.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
473 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
474 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
475 This section lists the various properties, grouped by purpose. Each
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
476 property also has a full reference page in <xref linkend="reference">.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
477 Properties related to values and expressions are described in more
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
478 detail in <xref linkend="language.values">. Properties related to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
479 header file generation and to the build process are described in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
480 <xref linkend="build">.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
481 </para>
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 <!-- {{{ User-visible -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
485
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
486 <sect2 id="language.properties.user">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
487 <title>Information-providing Properties</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 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
490 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
491 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
492 text: the <link linkend="ref.display">&display;</link> property gives
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
493 a textual alias for an option, which is usually more comprehensible
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
494 than something like <literal>CYGPKG_LIBC_TIME_ZONES`</literal>; the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
495 <link linkend="ref.description">&description;</link> property gives a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
496 longer description, typically a paragraph or so; the <link
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
497 linkend="ref.doc">&doc;</link> property specifies the location of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
498 additional on-line documentation related to a configuration option. In
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
499 the context of a graphical tool the &display; string will be the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
500 primary way for users to identify configuration options; the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
501 &description; paragraph will be visible whenever the option is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
502 selected; the on-line documentation will only be accessed when the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
503 user explicitly requests it.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
504 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
505 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
506 cdl_package CYGPKG_UITRON {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
507 display "uITRON compatibility layer"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
508 doc ref/ecos-ref.a.html
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
509 description "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
510 eCos supports a uITRON Compatibility Layer, providing
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
511 full Level S (Standard) compliance with Version 3.02 of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
512 the uITRON Standard, plus many Level E (Extended) features.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
513 uITRON is the premier Japanese embedded RTOS standard."
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
514 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
515 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
516 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
517 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
518 All three properties take a single argument. For &display; and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
519 &description; this argument is just a string. For &doc; it should be a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
520 pointer to a suitable HTML file, optionally including an anchor within
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
521 that page. If the <link linkend="package.hierarchy">directory layout
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
522 conventions</link> are observed then the component framework will look
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
523 for the HTML file in the package's <filename
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
524 class="directory">doc</filename> sub-directory, otherwise the &doc;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
525 filename will be treated as relative to the package's top-level directory.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
526 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
527 </sect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
528
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
529 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
530 <!-- {{{ Hierarchy -->
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 <sect2 id="language.properties.hierarchy">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
533 <title>The Configuration Hierarchy</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
534 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
535 There are two properties related to the hierarchical organization of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
536 components and options: <link linkend="ref.parent">&parent;</link> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
537 <link linkend="ref.script">&script;</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
538 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
539 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
540 The &parent; property can be used to move a &CDL; entity somewhere
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
541 else in the hierarchy. The most common use is for packages, to avoid
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
542 having all the packages appear at the top-level of the configuration
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
543 hierarchy. For example an architectural HAL package such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
544 <varname>CYGPKG_HAL_SH</varname> is placed below the common HAL
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
545 package <varname>CYGPKG_HAL</varname> using a &parent; property.
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 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
548 cdl_package CYGPKG_HAL_SH {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
549 display "SH architecture"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
550 parent CYGPKG_HAL
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
551 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
552 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
553 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
554 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
555 The &parent; property can also 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
556 &cdl-component;, &cdl-option; or &cdl-interface;, but this is less
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
557 common. However care has to be taken since excessive re-parenting can
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
558 be confusing. Care also has to be taken when reparenting below some
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
559 other package that may not actually be loaded in a given
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
560 configuration, since the resulting behavior is undefined.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
561 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
562 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
563 As a special case, if the parent is the empty string then the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
564 &CDL; entity is placed at the root of the hierarchy. This is useful
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
565 for global preferences, default compiler flags, and other settings
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
566 that may affect every package.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
567 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
568 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
569 The &script; 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
570 &cdl-component; command. The property takes a single filename as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
571 argument, and this should be another &CDL; script containing
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
572 additional options, sub-components and interfaces that should go below
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
573 the current component in the hierarchy. If the <link
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
574 linkend="package.hierarchy">directory layout conventions</link> are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
575 observed then the component framework will look for the specified file
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
576 relative to the <filename class="directory">cdl</filename>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
577 subdirectory of the package, otherwise the filename will be treated as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
578 relative to the package's top-level directory.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
579 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
580 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
581 cdl_component CYGPKG_LIBC_STDIO {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
582 display "Standard input/output functions"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
583 flavor bool
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
584 requires CYGPKG_IO
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
585 requires CYGPKG_IO_SERIAL_HALDIAG
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
586 default_value 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
587 description "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
588 This enables support for standard I/O functions from &lt;stdio.h&gt;."
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
589
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
590 script stdio.cdl
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
591 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
592 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
593
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
594 </sect2>
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 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
597 <!-- {{{ Value -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
598
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
599 <sect2 id="language.properties.value">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
600 <title>Value-related Properties</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
601 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
602 There are seven properties which are related to option values and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
603 state: <link linkend="ref.flavor">&flavor;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
604 <link linkend="ref.calculated">&calculated;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
605 <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
606 <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
607 <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
608 <link linkend="ref.implements">&implements;</link>, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
609 <link linkend="ref.requires">&requires;</link>. More detailed
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
610 information can be found in <xref linkend="language.values">.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
611 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
612 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
613 In the context of configurability, the concept of an option's value is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
614 somewhat non-trivial. First an option may or may not be loaded: it is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
615 possible to build a configuration which has the math library but not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
616 the kernel; however the math library's &CDL; scripts still reference
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
617 kernel options, for example
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
618 <varname>CYGSEM_LIBM_THREAD_SAFE_COMPAT_MODE</varname> has a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
619 &requires; constraint on
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
620 <varname>CYGVAR_KERNEL_THREADS_DATA</varname>. Even if an option is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
621 loaded it may or may not be active, depending on what is happening
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
622 higher up in the hierarchy: if the C library's
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
623 <varname>CYGPKG_LIBC_STDIO</varname> component is disabled then some
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
624 other options such as <varname>CYGNUM_LIBC_STDIO_BUFSIZE</varname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
625 become irrelevant. In addition each option has both a boolean
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
626 enabled/disabled flag and a data part. For many options only the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
627 boolean flag is of interest, while for others only the data part is of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
628 interest. The &flavor; property can be used to control this:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
629 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
630 <variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
631 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
632 <term><literal>flavor none</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
633 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
634 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
635 This flavor indicates that neither the boolean nor the data parts are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
636 user-modifiable: the option is always enabled and the data is always
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
637 set to <literal>1</literal>. The most common use for this is to have a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
638 component that just acts as a placeholder in the hierarchy, allowing
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
639 various options to be grouped below it.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
640 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
641 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
642 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
643 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
644 <term><literal>flavor bool</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
645 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
646 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
647 Only the boolean part of the option is user-modifiable. The data part
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
648 is fixed at <literal>1</literal>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
649 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
650 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
651 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
652 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
653 <term><literal>flavor data</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
654 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
655 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
656 Only the data part of the option is user-modifiable. The boolean part
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
657 is fixed at enabled.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
658 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
659 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
660 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
661 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
662 <term><literal>flavor booldata</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
663 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
664 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
665 Both the boolean and the data part of the option are user-modifiable.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
666 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
667 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
668 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
669 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
670 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
671 For more details of &CDL; flavors and how a flavor affects expression
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
672 evaluation, and other consequences, see <xref
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
673 linkend="language.values">. The &flavor; property cannot be used for a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
674 package because packages always have the <literal>booldata</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
675 flavor. Options and components have the <literal>bool</literal> flavor
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
676 by default, since most configuration choices are simple yes-or-no
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
677 choices. Interfaces have the <literal>data</literal> flavor by default.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
678 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
679 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
680 The &calculated; property can be used for options which should not be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
681 user-modifiable, but which instead are fixed by the target hardware or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
682 determined from the current values of other options. In general
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
683 &calculated; options should be avoided, since they can be confusing to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
684 users who need to figure out whether or not a particular option can
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
685 actually be changed. There are a number of valid uses for &calculated;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
686 options, and quite a few invalid ones as well. The <link
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
687 linkend="ref.calculated">reference packages</link> should be consulted
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
688 for further details. The property takes an <link
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
689 linkend="language.expression">ordinary &CDL; expression</link> as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
690 argument, for example:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
691 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
692 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
693 # 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
694 # targets.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
695 cdl_option CYGNUM_HAL_RTC_PERIOD {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
696 display "Real-time clock period"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
697 flavor data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
698 calculated 12500
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
699 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
700 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
701 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
702 The &calculated; property cannot be used for packages or interfaces.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
703 The value of a package always corresponds to the version of that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
704 package which is loaded, and this is under user control. Interfaces
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
705 are implicitly calculated, based on the number of active and enabled
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
706 implementors.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
707 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
708 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
709 The &default-value; property is similar to &calculated;, but only
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
710 specifies a default value which users can modify. Again this property
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
711 is not relevant to packages or interfaces. A typical example would be:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
712 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
713 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
714 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
715 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
716 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
717 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
718 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
719 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
720 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
721 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
722 The &legal-values; property imposes a constraint on the possible
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
723 values of the data part of an option. Hence it is only applicable to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
724 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
725 <literal>booldata</literal> flavors. It cannot be used for a package
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
726 since the only valid value for a package is its version number. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
727 arguments to the &legal-values; property should constitute a <link
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
728 linkend="language.list-expression">&CDL; list expression</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
729 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
730 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
731 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
732 display "Default Standard Time offset"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
733 flavor data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
734 legal_values -- -90000 to 90000
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
735 default_value -- 0
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
736 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
737 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
738 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
739 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
740 The &active-if; property does not relate directly to an option's
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
741 value, but rather to its active state. Usually this is controlled via
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
742 the configuration hierarchy: if the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
743 <varname>CYGPKG_LIBC_STDIO</varname> component is disabled then all
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
744 options below it are inactive and do not have any consequences.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
745 In some cases the hierarchy does not provide sufficient control, for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
746 example an option should only be active if two disjoint sets of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
747 conditions are satisfied: the hierarchy could be used for one of these
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
748 conditions, and an additional &active-if; property could be used for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
749 the other one. The arguments to &active-if; should constitute a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
750 <link linkend="language.goal-expression">&CDL; goal expression</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
751 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
752 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
753 # 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
754 cdl_option CYGDBG_KERNEL_INSTRUMENT_BINSEM {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
755 active_if CYGPKG_KERNEL_SYNCH
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
756 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
757 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
758 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
759 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
760 The &implements; property is related to the concept of <link
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
761 linkend="language.interface">&CDL; interfaces</link>. If an option is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
762 active and enabled and it implements a particular interface then it
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
763 contributes <literal>1</literal> to that interface's value.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
764 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
765 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
766 cdl_package CYGPKG_NET_EDB7XXX_ETH_DRIVERS {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
767 display "Cirrus Logic ethernet driver"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
768 implements CYGHWR_NET_DRIVERS
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
769 implements CYGHWR_NET_DRIVER_ETH0
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
770 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
771 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
772 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
773 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
774 The &requires; property is used to impose constraints on the user's
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
775 choices. For example it is unreasonable to expect the C library to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
776 provide thread-safe implementations of certain functions if the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
777 underlying kernel support has been disabled, or even if the kernel is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
778 not being used at all.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
779 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
780 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
781 cdl_option CYGSEM_LIBC_PER_THREAD_ERRNO {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
782 display "Per-thread errno"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
783 doc ref/ecos-ref.15.html
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
784 requires CYGVAR_KERNEL_THREADS_DATA
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
785 default_value 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
786 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
787 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
788 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
789 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
790 The arguments to the &requires; property should be a <link
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
791 linkend="language.goal-expression">&CDL; goal expression</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
792 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
793
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
794 </sect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
795
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
796 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
797 <!-- {{{ Header file generation -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
798
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
799 <sect2 id="language.properties.define">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
800 <title>Generating the Configuration Header Files</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
801 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
802 When creating or updating a build tree the component framework will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
803 also generate configuration header files, one per package. By default
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
804 it will generate a <literal>#define</literal> for each option,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
805 component or interface that is active and enabled. For options with
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
806 the <literal>data</literal> or <literal>booldata</literal> flavors the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
807 <literal>#define</literal> will use the option's data part, otherwise
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
808 it will use the constant <literal>1</literal>. Typical output would
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
809 include:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
810 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
811 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
812 #define CYGFUN_LIBC_TIME_POSIX 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
813 #define CYGNUM_LIBC_TIME_DST_DEFAULT_STATE -1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
814 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
815 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
816 There are six properties which can be used to control the header file
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
817 generation process:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
818 <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
819 <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
820 <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
821 <link linkend="ref.define">&define;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
822 <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
823 <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
824 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
825 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
826 By default the component framework will generate a configuration
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
827 header file for each package based on the package's name: everything
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
828 up to and including the first underscore is discarded, the rest of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
829 name is lower-cased, and a <literal>.h</literal> suffix is appended.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
830 For example the configuration header file for the kernel package
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
831 <varname>CYGPKG_KERNEL</varname> is <filename
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
832 class="headerfile">pkgconf/kernel.h</filename>. The &define-header;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
833 property can be used to specify an alternative filename. This applies
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
834 to all the components and options within a package, so it can only be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
835 used in the body of a &cdl-package; command. For example the following
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
836 specifies that the configuration header file for the SPARClite HAL
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
837 package is <filename
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
838 class="headerfile">pkgconf/hal_sparclite.h</filename>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
839 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
840 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
841 cdl_package CYGPKG_HAL_SPARCLITE {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
842 display "SPARClite architecture"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
843 parent CYGPKG_HAL
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
844 hardware
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
845 define_header hal_sparclite.h
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
846 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
847 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
848 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
849 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
850 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
851 At present the main use for the &define-header; property is related
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
852 to hardware packages, see the <link linkend="ref.hardware">reference
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
853 pages</link> for more details.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
854 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
855 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
856 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
857 The &no-define; property is used to suppress the generation of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
858 default <literal>#define</literal>. This can be useful if an option's
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
859 consequences are all related to the build process or to constraints,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
860 and the option is never actually checked in any source code. It can
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
861 also be useful in conjunction with the &define;, &if-define; or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
862 &define-proc; properties. The &no-define; property does not take any
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
863 arguments.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
864 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
865 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
866 cdl_component CYG_HAL_STARTUP {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
867 display "Startup type"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
868 flavor data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
869 legal_values { "RAM" "ROM" }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
870 default_value {"RAM"}
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
871 no_define
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
872 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
873 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
874 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
875 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
876 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
877 This example also illustrates the &define; property, which can be used
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
878 to generate a <literal>#define</literal> in addition to the default
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
879 one. It takes a single argument, the name of the symbol to be defined.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
880 It also takes options to control the configuration header file in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
881 which the symbol should be defined and the format to be used.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
882 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
883 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
884 The &define-format; property can be used to control how the value part
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
885 of the default <literal>#define</literal> gets formatted. For example
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
886 a format string of <literal>"0x%04x"</literal> could be used to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
887 generate a four-digit hexadecimal number.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
888 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
889 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
890 The &if-define; property is intended for use primarily to control
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
891 assertions, tracing, and similar functionality. It supports a specific
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
892 implementation model for these, allowing control at the grain of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
893 packages or even individual source files. The <link
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
894 linkend="ref.if-define">reference pages</link> provide additional
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
895 information.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
896 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
897 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
898 The &define-proc; property provides an escape mechanism for those
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
899 cases where something special has to happen at configuration header
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
900 file generation time. It takes a single argument, a fragment of &Tcl;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
901 code, which gets executed when the header file is generated. This code
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
902 can output arbitrary data to the header file, or perform any other
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
903 actions that might be appropriate.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
904 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
905
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
906 </sect2>
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 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
909 <!-- {{{ Builds -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
910
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
911 <sect2 id="language.properties.build">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
912 <title>Controlling what gets Built</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
913 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
914 There are six properties which affect the build process:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
915 <link linkend="ref.compile">&compile;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
916 <link linkend="ref.make">&make;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
917 <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
918 <link linkend="ref.library">&library;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
919 <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
920 <link linkend="ref.include-files">&include-files;</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
921 The last three apply to a package as a whole, and can only occur in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
922 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
923 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
924 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
925 Most of the source files that go into a package should simply be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
926 compiled with the appropriate compiler, selected by the target
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
927 architecture, and with the appropriate flags, with an additional set
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
928 defined by the target hardware and possible modifications on a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
929 per-package basis. The resulting object files will go into the library
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
930 <filename>libtarget.a</filename>, which can then be linked against
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
931 application code. The &compile; property is used to list these source
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
932 files:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
933 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
934 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
935 cdl_package CYGPKG_ERROR {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
936 display "Common error code support"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
937 compile strerror.cxx
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
938 include_dir cyg/error
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
939 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
940 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
941 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
942 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
943 The arguments to the &compile; property should be one or more source
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
944 files. Typically most of the sources will be needed for the package as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
945 a whole, and hence they will be listed in one or more &compile;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
946 properties in the body of the &cdl-package;. Some sources may be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
947 specific to particular configuration options, in other words there is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
948 no point in compiling them unless that option is enabled, in which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
949 case the sources should be listed in a &compile; property in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
950 corresponding &cdl-option;, &cdl-component; or &cdl-interface; body.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
951 </para>
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 Some packages may have more complicated build requirements, for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
954 example they may involve a special target such as a linker script
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
955 which should not end up in the usual library, or they may involve
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
956 special build steps for generating an object file. The &make; and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
957 &make-object; properties provide support for such requirements, for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
958 example:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
959 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
960 <programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
961 cdl_package CYGPKG_HAL_MN10300_AM33 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
962 display "MN10300 AM33 variant"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
963 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
964 make {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
965 &lt;PREFIX&gt;/lib/target.ld: &lt;PACKAGE&gt;/src/mn10300_am33.ld
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
966 $(CC) -E -P -Wp,-MD,target.tmp -DEXTRAS=1 -xc $(INCLUDE_PATH) \
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
967 $(CFLAGS) -o $@ $&lt;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
968 @echo $@ ": \\" &gt; $(notdir $@).deps
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
969 @tail +2 target.tmp &gt;&gt; $(notdir $@).deps
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
970 @echo &gt;&gt; $(notdir $@).deps
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
971 @rm target.tmp
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
972 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
973 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
974 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
975 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
976 For full details of custom build steps and the build process
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
977 generally, see <xref linkend="build">.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
978 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
979 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
980 By default all object files go into the library
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
981 <filename>libtarget.a</filename>. It is possible to override this at
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
982 the package level using the &library; property, but this should be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
983 avoided since it complicates application development: instead of just
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
984 linking with a single library for all &eCos;-related packages, it
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
985 suddenly becomes necessary to link with several libraries.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
986 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
987 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
988 The &include-dir; and &include-files; properties relate to a package's
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
989 exported header files. By default a package's header files will be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
990 exported to the <filename class="directory">install/include</filename>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
991 directory. This is the desired behavior for some packages like the C
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
992 library, since headers like <filename
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
993 class="headerfile">stdio.h</filename> should exist at that level.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
994 However if all header files were to end up in that directory then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
995 there would be a significant risk of a name clash. Instead it is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
996 better for packages to specify some sub-directory for their exported
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
997 header files, for example:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
998 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
999 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1000 cdl_package CYGPKG_INFRA {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1001 display "Infrastructure"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1002 include_dir cyg/infra
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1003 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1004 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1005 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1006 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1007 The various header files exported by the infrastructure, for example
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1008 <filename class="headerfile">cyg_ass.h</filename> and <filename
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1009 class="headerfile">cyg_trac.h</filename> will now end up in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1010 <filename class="directory">install/include/cyg/infra</filename>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1011 sub-directory, where a name clash is very unlikely.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1012 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1013 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1014 For packages which follow the <link
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1015 linkend="package.hierarchy">directory layout conventions</link> the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1016 component framework will assume that the package's
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1017 <filename class="directory">include</filename> sub-directory contains
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1018 all exported header files. If this is not the case, for example
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1019 because the package is sufficiently simple that the layout convention
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1020 is inappropriate, then the exported header files can be listed
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1021 explicitly in an &include-files; property.
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
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1024 </sect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1025
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1026 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1027 <!-- {{{ Miscellaneous -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1028
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1029 <sect2 id="language.properties.miscellaneous">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1030 <title>Miscellaneous Properties</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1031 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1032 The <link linkend="ref.hardware">&hardware;</link> property is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1033 only relevant to packages. Some packages such as device drivers and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1034 HAL packages are hardware-specific, and generally it makes no sense to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1035 add such packages to a configuration unless the corresponding hardware
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1036 is 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
1037 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
1038 property should be used to identify a hardware-specific package, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1039 does not take any arguments.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1040 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1041 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1042 cdl_package CYGPKG_HAL_MIPS {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1043 display "MIPS architecture"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1044 parent CYGPKG_HAL
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1045 hardware
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1046 include_dir cyg/hal
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1047 define_header hal_mips.h
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1048 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1049 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1050 </programlisting>
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 At present the &hardware; property is largely ignored by the component
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1053 framework. This may change in future releases.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1054 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1055 </sect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1056
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1057 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1058
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1059 </sect1>
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 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1062 <!-- {{{ Naming conventions -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1063
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1064 <sect1 id="language.naming">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1065 <title>Option Naming Convention</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1066 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1067 All the options in a given configuration live in the same namespace.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1068 Furthermore it is not possible for two separate options to have the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1069 same name, because this would make any references to those options in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1070 &CDL; expressions ambiguous. A naming convention exists to avoid
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1071 problems. It is recommended that component writers observe some or all
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1072 of this convention to reduce the probability of name clashes with
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1073 other packages.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1074 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1075 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1076 There is an important restriction on option names. Typically the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1077 component framework will output a <literal>#define</literal> for every
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1078 active and enabled option, using the name as the symbol being defined.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1079 This requires that all names are valid C preprocessor symbols, a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1080 limitation that is enforced even for options which have the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1081 &no-define; property. Preprocessor symbols can be any sequence of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1082 lower case letters <literal>a</literal>-<literal>z</literal>, upper
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1083 case letters, <literal>A</literal>-<literal>Z</literal>, the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1084 underscore character <literal>_</literal>, and the digits
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1085 <literal>0</literal>-<literal>9</literal>. The first character must be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1086 a non-digit. Using an underscore as the first character is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1087 discouraged, because that may clash with reserved language
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1088 identifiers. In addition there is a convention that preprocessor
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1089 symbols only use upper case letters, and some component writers may
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1090 wish to follow this convention.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1091 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1092 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1093 A typical option name could be something like
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1094 <varname>CYGSEM_KERNEL_SCHED_BITMAP</varname>. This name consists of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1095 several different parts:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1096 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1097 <orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1098 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1099 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1100 The first few characters, in this case the three letters
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1101 <literal>CYG</literal>, are used to identify the organization that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1102 produced the package. For historical reasons packages produced by Red
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1103 Hat tend to use the prefix <literal>CYG</literal> rather than
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1104 <literal>RHAT</literal>. Component writers should use their own
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1105 prefix: even when cutting and pasting from an existing &CDL; script
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1106 the prefix should be changed to something appropriate to their
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1107 organization.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1108 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1109 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1110 It can be argued that a short prefix, often limited to upper case
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1111 letters, is not sufficiently long to eliminate the possibility of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1112 name clashes. A longer prefix could be used, for example one based on
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1113 internet domain names. However the C preprocessor has no concept of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1114 namespaces or <literal>import</literal> directives, so it would always
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1115 be necessary to use the full option name in component source code
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1116 which gets tedious - option names tend to be long enough as it is.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1117 There is a small increased risk of name clashes, but this risk is felt
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1118 to be acceptable.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1119 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1120 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1121 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1122 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1123 The next three characters indicate the nature of the option, for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1124 example whether it affects the interface or just the implementation. A
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1125 list of common tags is given below.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1126 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1127 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1128 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1129 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1130 The <literal>KERNEL_SCHED</literal> part indicates the location of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1131 option within the overall hierarchy. In this case the option is part of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1132 the scheduling component of the kernel package. Having the hierarchy
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1133 details as part of the option name can help in understanding
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1134 configurable code and further reduces the probability of a name clash.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1135 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1136 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1137 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1138 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1139 The final part, <literal>BITMAP</literal>, identifies the option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1140 itself.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1141 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1142 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1143 </orderedlist>
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 The three-character tag is intended to provide some additional
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1146 information about the nature of the option. There are a number of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1147 pre-defined tags. However for many options there is a choice:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1148 options related to the platform should normally use
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1149 <literal>HWR</literal>, but numerical options should normally use
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1150 <literal>NUM</literal>; a platform-related numerical option such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1151 the size of an interrupt stack could therefore use either tag.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1152 There are no absolute rules, and it is left to component writers to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1153 interpret the following guidelines:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1154 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1155 <variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1156 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1157 <term><literal>xxxARC_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1158 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1159 The <literal>ARC</literal> tag is intended for options related
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1160 to the processor architecture. Typically such options will only occur
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1161 in architectural or variant HAL packages.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1162 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1163 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1164 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1165 <term><literal>xxxHWR_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1166 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1167 The <literal>HWR</literal> tag is intended for options related to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1168 the specific target board. Typically such options will only occur in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1169 platform HAL packages.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1170 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1171 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1172 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1173 <term><literal>xxxPKG_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1174 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1175 This tag is intended for packages or components, in other words
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1176 options which extend the configuration hierarchy. Arguably a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1177 <literal>COM</literal> tag would be more appropriate for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1178 components, but this could be confusing because of the considerable
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1179 number of computing terms that begin with com.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1180 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1181 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1182 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1183 <term><literal>xxxGLO_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1184 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1185 This is intended for global configuration options, especially
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1186 preferences.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1187 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1188 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1189 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1190 <term><literal>xxxDBG_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1191 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1192 The <literal>DBG</literal> tag indicates that the option is in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1193 some way related to debugging, for example it may enable assertions in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1194 some part of the system.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1195 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1196 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1197 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1198 <term><literal>xxxTST_</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 This tag is for testing-related options. Typically these do not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1201 affect actual application code, instead they control the interaction
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1202 between target-side test cases and a host-side testing infrastructure.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1203 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1204 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1205 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1206 <term><literal>xxxFUN_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1207 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1208 This is for configuration options which affect the interface of a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1209 package. There are a number of related tag which are also
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1210 interface-related. <literal>xxxFUN_</literal> is intended primarily
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1211 for options that control whether or not one or more functions are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1212 provided by the package, but can also be used if none of the other
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1213 interface-related tags is applicable.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1214 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1215 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1216 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1217 <term><literal>xxxVAR_</literal></term>
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 This is analogous to <literal>FUN</literal> but controls the presence
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1220 or absence of one or more variables or objects.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1221 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1222 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1223 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1224 <term><literal>xxxCLS_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1225 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1226 The <literal>CLS</literal> tag is intended only for packages that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1227 provide an object-oriented interface, and controls the presence or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1228 absence of an entire class.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1229 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1230 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1231 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1232 <term><literal>xxxMFN_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1233 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1234 This is also for object-orientated interfaces, and indicates the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1235 presence or absence of a member function rather than an entire class.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1236 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1237 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1238 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1239 <term><literal>xxxSEM_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1240 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1241 A <literal>SEM</literal> option does not affect the interface (or if
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1242 does affect the interface, this is incidental). Instead it is used for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1243 options which have a fundamental effect on the semantic behavior of a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1244 package. For example the choice of kernel schedulers is semantic in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1245 nature: it does not affect the interface, in particular the function
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1246 <function>cyg_thread_create</function> exists irrespective of which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1247 scheduler has been selected. However it does have a major impact on
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1248 the system's behavior.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1249 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1250 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1251 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1252 <term><literal>xxxIMP_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1253 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1254 <literal>IMP</literal> is for implementation options. These do not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1255 affect either the interface or the semantic behavior (with the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1256 possible exception of timing-related changes). A typical
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1257 implementation option controls whether or not a particular function or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1258 set of functions should get inlined.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1259 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1260 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1261 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1262 <term><literal>xxxNUM_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1263 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1264 This tag is for numerical options, for example the number of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1265 scheduling priority levels.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1266 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1267 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1268 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1269 <term><literal>xxxDAT_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1270 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1271 This is for data items that are not numerical in nature, for example a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1272 device name.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1273 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1274 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1275 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1276 <term><literal>xxxBLD_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1277 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1278 The <literal>BLD</literal> tag indicates an option that affects
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1279 the build process, for example compiler flag settings.
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 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1282 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1283 <term><literal>xxxINT_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1284 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1285 This should normally be used for &CDL; interfaces, which is a language
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1286 construct that is largely independent from the interface exported by a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1287 package via its header files. For more details of &CDL; interfaces
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1288 see <xref linkend="language.interface">.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1289 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1290 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1291 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1292 <term><literal>xxxPRI_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1293 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1294 This tag is not normally used for configuration options. Instead
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1295 it is used by &CDL; scripts to pass additional private information to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1296 the source code via the configuration header files, typically inside a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1297 &define-proc; property.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1298 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1299 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1300 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1301 <term><literal>xxxSRC_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1302 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1303 This tag is not normally used for configuration options. Instead
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1304 it can be used by package source code to interact with such options,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1305 especially in the context of the &if-define; property.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1306 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1307 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1308 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1309
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1310 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1311 There is one special case of a potential name clash that is worth
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1312 mentioning here. When the component framework generates a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1313 configuration header file for a given package, by default it will use
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1314 a name derived from the package name (the &define-header; property can
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1315 be used to override this). The file name is constructed from the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1316 package name by removing everything up to and including the first
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1317 underscore, converting the remainder of the name to lower case, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1318 appending a <literal>.h</literal> suffix. For example the kernel
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1319 package <varname>CYGPKG_KERNEL</varname> will involve a header file
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1320 <filename class="headerfile">pkgconf/kernel.h</filename>. If a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1321 configuration contained some other package
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1322 <varname>XYZPKG_KERNEL</varname> then this would attempt to use the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1323 same configuration header file, with unfortunate effects. Case
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1324 sensitivity could introduce problems as well, so a package
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1325 <varname>xyzpkg_kernel</varname> would involve the same problem. Even
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1326 if the header file names preserved the case of the package name, not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1327 all file systems are case sensitive. There is no simple solution to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1328 this problem. Changing the names of the generated configuration header
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1329 files would involve a major incompatible change to the interface, to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1330 solve a problem which is essentially hypothetical in nature.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1331 </para>
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 </sect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1334
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1335 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1336 <!-- {{{ Introduction to Tcl -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1337
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1338 <sect1 id="language.tcl">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1339 <title>An Introduction to Tcl</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1340
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1341 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1342 All &CDL; scripts are implemented as &Tcl; scripts, and are read in by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1343 running the data through a standard &Tcl; interpreter, extended with a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1344 small number of additional commands such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1345 <literal>cdl_option</literal> and <literal>cdl_component</literal>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1346 Often it is not necessary to know the full details of &Tcl; syntax.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1347 Instead it is possible to copy an existing script, perform some copy
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1348 and paste operations, and make appropriate changes to names and to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1349 various properties. However there are also cases where an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1350 understanding of &Tcl; syntax is very desirable, for example:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1351 </para>
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 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1354 cdl_option CYGDAT_UITRON_MEMPOOLFIXED_EXTERNS {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1355 display "Externs for initialization"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1356 flavor data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1357 default_value {"static char fpool1[ 2000 ], \\\n\
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1358 fpool2[ 2000 ], \\\n\
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1359 fpool3[ 2000 ];"}
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1360 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1361 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1362 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1363
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1364 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1365 This causes the &cdl-option; command to be executed, which in turn
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1366 evaluates its body in a recursive invocation of the &Tcl; interpreter.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1367 When the &default-value; property is encountered the braces around the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1368 value part are processed by the interpreter, stopping it from doing
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1369 further processing of the braced contents (except for backslash
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1370 processing at the end of a line, that is special). In particular it
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1371 prevents command substitution for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1372 <literal>[&nbsp;2000&nbsp;]</literal>. A single argument will be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1373 passed to the &default-value; command which expects a &CDL;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1374 expression, so the expression parsing code is passed the following:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1375 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1376
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1377 <screen width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1378 "static char fpool1[ 2000 ], \\\n fpool2[ 2000 ], \\\n fpool3[ 2000 ];"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1379 </screen>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1380
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1381 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1382 The &CDL; expression parsing code will treat this as a simple string
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1383 constant, as opposed to a more complicated expression involving other
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1384 options and various operators. The string parsing code will perform
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1385 the usual backslash substitutions so the actual default value will be:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1386 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1387 <screen width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1388 static char fpool1[ 2000 ], \
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1389 fpool2[ 2000 ], \
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1390 fpool3[ 2000 ];
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1391 </screen>
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 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1394 If the user does not modify the option's value then the following
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1395 will be generated in the appropriate configuration header file:
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 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1398 #define CYGDAT_UITRON_MEMPOOLFIXED_EXTERNS static char fpool1[ 2000 ], \
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1399 fpool2[ 2000 ], \
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1400 fpool3[ 2000 ];
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1401 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1402
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1403 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1404 Getting this desired result usually requires an understanding of both
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1405 &Tcl; syntax and &CDL; expression syntax. Sometimes it is possible to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1406 substitute a certain amount of trial and error instead, but this may
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1407 prove frustrating. It is also worth pointing out that many &CDL;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1408 scripts do not involve this level of complexity. On the other hand,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1409 some of the more advanced features of the &CDL; language involve
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1410 fragments of &Tcl; code, for example the &define-proc; property. To
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1411 use these component writers will need to know about the full &Tcl;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1412 language as well as the syntax.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1413 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1414 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1415 Although the current example may seem to suggest that &Tcl; is rather
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1416 complicated, it is actually a very simple yet powerful scripting
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1417 language: the syntax is defined by just eleven rules. On occasion this
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1418 simplicity means that Tcl's behavior is subtly different from other
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1419 languages, which can confuse newcomers.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1420 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1421 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1422 When the Tcl interpreter is passed some data such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1423 <literal>puts&nbsp;Hello</literal>, it splits this data into a command
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1424 and its arguments. The command will be terminated by a newline or by a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1425 semicolon, unless one of the quoting mechanisms is used. The command
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1426 and each of its arguments are separated by white space. So in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1427 following example:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1428 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1429 <screen width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1430 puts Hello
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1431 set x 42
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1432 </screen>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1433 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1434 This will result in two separate commands being executed. The first
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1435 command is <literal>puts</literal> and is passed a single argument,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1436 <literal>Hello</literal>. The second command is <literal>set</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1437 and is passed two arguments, <literal>x</literal> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1438 <literal>42</literal>. The intervening newline character serves to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1439 terminate the first command, and a semi-colon separator could be used
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1440 instead:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1441 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1442 <screen width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1443 puts Hello;set x 42
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1444 </screen>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1445 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1446 Any white space surrounding the semicolon is just ignored because it
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1447 does not serve to separate arguments.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1448 </para>
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 Now consider the following:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1451 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1452 <screen width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1453 set x Hello world
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1454 </screen>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1455 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1456 This is not valid &Tcl;. It is an attempt to invoke the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1457 <literal>set</literal> command with three arguments:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1458 <literal>x</literal>, <literal>Hello</literal>, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1459 <literal>world</literal>. The <literal>set</literal> only takes two
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1460 arguments, a variable name and a value, so it is necessary to combine
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1461 the data into a single argument by quoting:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1462 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1463 <screen width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1464 set x "Hello world"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1465 </screen>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1466 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1467 When the &Tcl; interpreter encounters the first quote character it
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1468 treats all subsequent data up to but not including the closing quote
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1469 as part of the current argument. The quote marks are removed by the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1470 interpreter, so the second argument passed to the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1471 <literal>set</literal> command is just <literal>Hello world</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1472 without the quote characters. This can be significant in the context
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1473 of &CDL; scripts. For example:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1474 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1475 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1476 cdl_option CYG_HAL_STARTUP {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1477 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1478 default_value "RAM"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1479 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1480 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1481 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1482 The &Tcl; interpreter strips off the quote marks so the &CDL;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1483 expression parsing code sees <literal>RAM</literal> instead of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1484 <literal>"RAM"</literal>. It will treat this as a reference to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1485 some unknown option <varname>RAM</varname> rather than as a string
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1486 constant, and the expression evaluation code will use a value of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1487 <literal>0</literal> when it encounters an option that is not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1488 currently loaded. Therefore the option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1489 <varname>CYG_HAL_STARTUP</varname> ends up with a default value of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1490 <literal>0</literal>. Either braces or backslashes should be used to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1491 avoid this, for example
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1492 <literal>default_value&nbsp;{&nbsp;"RAM"&nbsp;}</literal>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1493 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1494 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1495 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1496 There are long-term plans to implement some sort of &CDL; validation
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1497 utility <application class="software">cdllint</application> which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1498 could catch common errors like this one.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1499 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1500 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1501 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1502 A quoted argument continues until the closing quote character is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1503 encountered, which means that it can span multiple lines. Newline or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1504 semicolon characters do not terminate the current command in such
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1505 cases. &description; properties usually make use of this:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1506 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1507 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1508 cdl_package CYGPKG_ERROR {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1509 description "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1510 This package contains the common list of error and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1511 status codes. It is held centrally to allow
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1512 packages to interchange error codes and status
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1513 codes in a common way, rather than each package
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1514 having its own conventions for error/status
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1515 reporting. The error codes are modelled on the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1516 POSIX style naming e.g. EINVAL etc. This package
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1517 also provides the standard strerror() function to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1518 convert error codes to textual representation."
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1519 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1520 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1521 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1522 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1523 The &Tcl; interpreter supports much the same forms of backslash
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1524 substitution as other common programming languages. Some backslash
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1525 sequences such as <literal>\n</literal> will be replaced by the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1526 appropriate character. The sequence <literal>\\</literal> will be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1527 replaced by a single backslash. A backslash at the very end of a line
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1528 will cause that backslash, the newline character, and any white space
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1529 at the start of the next line to be replaced by a single space. Hence
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1530 the following two Tcl commands are equivalent:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1531 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1532 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1533 puts "Hello\nworld\n"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1534 puts \
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1535 "Hello
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1536 world
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1537 "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1538 </programlisting>
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 If a &description; string needs to contain quote marks or other
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1541 special characters then backslash escapes can be used. In addition to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1542 quote and backslash characters, the Tcl interpreter treats square
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1543 brackets, the <literal>$</literal> character, and braces specially.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1544 Square brackets are used for command substitution, for example:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1545 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1546 <screen width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1547 puts "The answer is [expr 6 * 9]"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1548 </screen>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1549 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1550 When the Tcl interpreter encounters the square brackets it will treat
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1551 the contents as another command that should be executed first, and the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1552 result of executing that is used when continuing to process the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1553 script. In this case the Tcl interpreter will execute the command
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1554 <literal>expr 6 * 9</literal>, yielding a result of 42
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1555 <footnote>
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 It is possible that some versions of the Tcl interpreter will instead
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1558 produce a result of 54 when asked to multiply six by nine. Appropriate
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1559 <ulink url="http://www.douglasadams.com/creations/hhgg.html">reference
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1560 documentation</ulink> should be consulted for more information on why
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1561 42 is in fact the correct answer.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1562 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1563 </footnote>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1564 and then the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1565 Tcl interpreter will execute <literal>puts "The answer is 42"</literal>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1566 It should be noted that the interpreter performs only one level
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1567 of substitution: if the result of performing command substitution
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1568 performs further special characters such as square brackets then these
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1569 will not be treated specially.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1570 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1571 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1572 Command substitution will not prove useful for many &CDL; scripts,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1573 except for e.g. a &define-proc; property which involves a fragment of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1574 &Tcl; code. Potentially there are some interesting uses, for example
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1575 to internationalize &display; strings. However care does have to be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1576 taken to avoid unexpected command substitution, for example if an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1577 option description involves square brackets then typically these would
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1578 require backslash-escapes.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1579 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1580 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1581 The <literal>$</literal> character is used in Tcl scripts to perform
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1582 variable substitution:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1583 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1584 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1585 set x [expr 6 * 9]
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1586 puts "The answer is $x"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1587 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1588 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1589 Variable substitution, like command substitution, is unlikely to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1590 prove useful for many &CDL; scripts except in the context of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1591 &Tcl; fragments. If it is necessary to have a <literal>$</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1592 character then a backslash escape may have to be used.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1593 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1594 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1595 Braces are used to collect a sequence of characters into a single
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1596 argument, just like quotes. The difference is that variable, command
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1597 and backslash substitution do not occur inside braces (with the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1598 sole exception of backslash substitution at the end of a line).
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1599 Therefore given a line in a &CDL; script such as:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1600 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1601 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1602 default_value {"RAM"}
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1603 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1604 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1605 The braces are stripped off by the &Tcl; interpreter, leaving
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1606 <literal>"RAM"</literal> which will be handled as a string constant by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1607 the expression parsing code. The same effect could be achieved using
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1608 one of the following:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1609 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1610 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1611 default_value \"RAM\"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1612 default_value "\"RAM\""
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1613 </programlisting>
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 Generally the use of braces is less confusing. At this stage it is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1616 worth noting that the basic format of &CDL; data makes use of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1617 braces:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1618 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1619 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1620 cdl_option &lt;name&gt; {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1621 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1622 };
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1623 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1624 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1625 The &cdl-option; command is passed two arguments, a name and a body,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1626 where the body consists of everything inside the braces but not the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1627 braces themselves. This body can then be executed in a recursive
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1628 invocation of the &Tcl; interpreter. If a &CDL; script contains
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1629 mismatched braces then the interpreter is likely to get rather
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1630 confused and the resulting diagnostics may be difficult to understand.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1631 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1632 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1633 Comments in Tcl scripts are introduced by a hash character
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1634 <literal>#</literal>. However, a hash character only introduces a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1635 comment if it occurs where a command is expected. Consider the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1636 following:
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 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1639 # This is a comment
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1640 puts "Hello" # world
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1641 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1642 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1643 The first line is a valid comment, since the hash character occurs
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1644 right at the start where a command name is expected. The second line
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1645 does not contain a comment. Instead it is an attempt to invoke the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1646 <literal>puts</literal> command with three arguments:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1647 <literal>Hello</literal>, <literal>#</literal> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1648 <literal>world</literal>. These are not valid arguments for the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1649 <literal>puts</literal> command so an error will be raised.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1650 If the second line was rewritten as:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1651 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1652 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1653 puts "Hello"; # world
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1654 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1655 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1656 then this is a valid Tcl script. The semicolon identifies the end of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1657 the current command, so the hash character occurs at a point where the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1658 next command would start and hence it is interpreted as the start of a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1659 comment.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1660 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1661 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1662 This handling of comments can lead to subtle behavior. Consider the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1663 following:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1664 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1665 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1666 cdl_option WHATEVER {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1667 # This is a comment }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1668 default_value 0
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1669 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1670 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1671 </programlisting>
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 Consider the way the Tcl interpreter processes this. The command name
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1674 and the first argument do not pose any special difficulties. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1675 opening brace is interpreted as the start of the next argument, which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1676 continues until a closing brace is encountered. In this case the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1677 closing brace occurs on the second line, so the second argument passed
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1678 to <literal>cdl_option</literal> is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1679 <literal>\n&nbsp;&nbsp;&nbsp;&nbsp;#&nbsp;This&nbsp;is&nbsp;a&nbsp;comment
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1680 </literal>. This second argument is processed in a recursive
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1681 invocation of the Tcl interpreter and does not contain any commands,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1682 just a comment. Top-level script processing then resumes, and the next
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1683 command that is encountered is <literal>default_value</literal>. Since
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1684 the parser is not currently processing a configuration option this is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1685 an error. Later on the Tcl interpreter would encounter a closing brace
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1686 by itself, which is also an error.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1687 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1688 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1689 For component writers who need more information about &Tcl;,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1690 especially about the language rather than the syntax, various
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1691 resources are available. A reasonable starting point is the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1692 <ulink url="http://dev.scriptics.com/scripting/">Scriptics developer
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1693 web site</ulink>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1694 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1695 </sect1>
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 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1698 <!-- {{{ Values and Expressions -->
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 <sect1 id="language.values">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1701 <title>Values and Expressions</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1702
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1703 <!-- {{{ Introit -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1704
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1705 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1706 It is fairly reasonable to expect that enabling or disabling a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1707 configuration option such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1708 <varname>CYGVAR_KERNEL_THREADS_DATA</varname> in some way affects its
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1709 <emphasis>value</emphasis>. This will have an effect on any
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1710 expressions that reference this option such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1711 <literal>requires&nbsp;CYGVAR_KERNEL_THREADS_DATA</literal>. It will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1712 also affect the consequences of that option: how it affects the build
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1713 process and what happens to any constraints that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1714 <varname>CYGVAR_KERNEL_THREADS_DATA</varname> may impose (as opposed
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1715 to constraints on this option imposed by others).
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1716 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1717 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1718 In a language like C the handling of variables is relatively
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1719 straightforward. If a variable <varname>x</varname> gets referenced in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1720 an expression such as <literal>if&nbsp;(x&nbsp;!=&nbsp;0)</literal>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1721 and that variable is not defined anywhere, then the code will fail to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1722 build, typically with an unresolved error at link-time. Also in C
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1723 a variable <varname>x</varname> does not live in any hierarchy, so its
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1724 value for the purposes of expression evaluation is not affected by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1725 anything else. C variables also have a clear type such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1726 <literal>int</literal> or <literal>long&nbsp;double</literal>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1727 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1728 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1729 In &CDL; things are not so straightforward.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1730 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1731
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1732 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1733 <!-- {{{ Option Values -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1734
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1735 <sect2 id="language.values.value">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1736 <!-- {{{ Introit -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1737
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1738 <title>Option Values</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1739
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1740 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1741 There are four factors which go into an option's value:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1742 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1743 <orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1744 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1745 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1746 An option may or may not be loaded.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1747 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1748 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1749 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1750 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1751 If the option is loaded, it may or may not be active.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1752 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1753 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1754 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1755 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1756 Even if the option is active, it may or may not be enabled.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1757 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1758 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1759 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1760 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1761 If the option is loaded, active and enabled then it will have some
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1762 associated data which constitutes its value.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1763 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1764 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1765 </orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1766
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 <!-- {{{ Loaded -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1769
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1770 <sect3 id="language.values.value.loaded">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1771 <title>Is the Option Loaded?</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1772
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 At any one time a configuration will contain only a subset of all
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1775 possible packages. In fact it is impossible to combine certain
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1776 packages in 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
1777 packages should contain a set of options defining endianness, the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1778 sizes of basic data types and so on (many of which will of course be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1779 constant for any given architecture). Any attempt to load two
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1780 architectural HAL packages into a configuration will fail because of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1781 the resulting name clash. Since &CDL; expressions can reference
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1782 options in other packages, and often need to do so, it is essential to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1783 define the resulting behavior.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1784 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1785 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1786 One complication is that the component framework does not know about
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1787 every single option in every single package. Obviously it cannot know
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1788 about packages from arbitrary third parties which have not been
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1789 installed. Even for packages which have been installed, the current
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1790 repository database does not hold details of every option, only of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1791 packages themselves. If a &CDL; expression contains a reference to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1792 some option <varname>CYGSEM_KERNEL_SCHED_TIMESLICE</varname> then the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1793 component framework will only know about this option if the kernel
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1794 package is actually loaded into the current configuration. If the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1795 package is not loaded then theoretically the framework might guess
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1796 that the option is somehow related to the kernel by examining the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1797 option name but this would not be robust: the option could easily be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1798 part of some other package that violates the naming convention.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1799 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1800 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1801 Assume that the user is building a minimal configuration which does
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1802 not contain the kernel package, but does have other packages which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1803 contain the following constraints:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1804 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1805 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1806 requires CYGPKG_KERNEL
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1807 requires CYGPKG_KERNEL_THREADS_DATA
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1808 requires !CYGSEM_KERNEL_SCHED_TIMESLICE
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1809 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1810 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1811 Clearly the first constraint is not satisfied because the kernel is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1812 not loaded. The second constraint is also not satisfied. The third
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1813 constraint is trivially satisfied: if there is no kernel then the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1814 kernel's timeslicing support cannot possibly be enabled.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1815 </para>
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 Any options which are not in the current configuration are handled as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1818 follows:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1819 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1820 <orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1821 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1822 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1823 Any references to that option will evaluate to <literal>0</literal>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1824 so <literal>requires&nbsp;!CYGSEM_KERNEL_SCHED_TIMESLICE</literal> will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1825 be satisfied but
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1826 <literal>requires&nbsp;CYGSEM_KERNEL_THREADS_DATA</literal> will not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1827 be satisfied.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1828 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1829 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1830 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1831 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1832 An option that is not loaded has no consequences on the build process.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1833 It cannot directly result in any <literal>#define's</literal> in a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1834 configuration header file, nor in any files being compiled. This is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1835 only reasonable: if the option is not loaded then the component
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1836 framework has no way of knowing about any &compile; or similar
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1837 properties. An option that is not loaded can have indirect
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1838 consequences by being referenced in &CDL; expressions.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1839 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1840 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1841 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1842 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1843 An option that is not loaded cannot impose any constraints on the rest
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1844 of the configuration. Again this is the only reasonable behavior: if
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1845 the option is not loaded then any associated &requires; or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1846 &legal-values; properties will not be known.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1847 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1848 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1849 </orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1850
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1851 </sect3>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1852
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 <!-- {{{ Active -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1855
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1856 <sect3 id="language.values.value.active">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1857 <title>Is the Option Active</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1858
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1859 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1860 The next issue to consider is whether or not a particular option is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1861 active. Configuration options are organized in a hierarchy of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1862 components and sub-components. For example the C library package
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1863 contains a component <varname>CYGPKG_LIBC_STDIO</varname> containing
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1864 all the options related to standard I/O. If a user disables the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1865 component as a whole then all the options below it become inactive: it
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1866 makes no sense to disable all stdio functionality and then manipulate
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1867 the buffer sizes.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1868 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1869 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1870 Inactive is not quite the same as disabled, although the effects are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1871 similar. The value of an inactive option is preserved. If the user
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1872 modifies a buffer size option, then disables the whole stdio
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1873 component, the buffer size value remains in case the stdio component
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1874 is re-enabled later on. Some tools such as the graphical configuration
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1875 tool will treat inactive options specially, for example such options
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1876 may be grayed out.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1877 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1878 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1879 The active or inactive state of an option may affect other packages.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1880 For example a package may use the <function>sprintf</function>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1881 function and require support for floating point conversions, a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1882 constraint that is not satisfied if the relevant option is inactive.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1883 It is necessary to define exactly what it means for an option to be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1884 inactive:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1885 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1886 <orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1887 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1888 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1889 An option is inactive if its parent is either inactive or disabled.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1890 For example if <varname>CYGPKG_LIBC_STDIO</varname> is disabled then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1891 all the options and sub-components become inactive; since
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1892 <varname>CYGPKG_LIBC_STDIO_FLOATING_POINT</varname> is now inactive,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1893 <varname>CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT</varname> is inactive
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1894 as well.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1895 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1896 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1897 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1898 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1899 Options may also be inactive as a result of an &active-if; property.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1900 This is useful if a particular option is only relevant if two or more
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1901 disjoint sets of conditions need to be satisfied, since the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1902 hierarchical structure can only cope with at most one such set.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1903 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1904 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1905 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1906 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1907 If an option is inactive then any references to that option in &CDL;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1908 expressions will evaluate to <literal>0</literal>. Hence a constraint
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1909 of the form
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1910 <literal>requires&nbsp;CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1911 is not satisfied if the entire stdio component is disabled.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1912 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1913 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1914 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1915 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1916 An option that is inactive has no consequences on the build process.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1917 No <literal>#define</literal> will be generated. Any &compile; or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1918 similar properties will be ignored.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1919 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1920 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1921 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1922 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1923 An option that is inactive cannot impose any constraints on the rest
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1924 of the configuration. For example
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1925 <varname>CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT</varname> has a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1926 dependency <literal>requires&nbsp;CYGPKG_LIBM</literal>, but if all of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1927 the stdio functionality is disabled then this constraint is ignored
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1928 (although of course there may be other packages which have a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1929 dependency on <varname>CYGPKG_LIBM</varname>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1930 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1931 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1932 </orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1933 </sect3>
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 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1936 <!-- {{{ Enabled/data -->
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 <sect3 id="language.values.value.enabled">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1939 <title>Is the Option Enabled? What is the Data?</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1940
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1941 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1942 The majority of configuration options are boolean in nature, so the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1943 user can either enable or disable some functionality. Some options are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1944 different. For example <varname>CYGNUM_LIBC_STDIO_BUFSIZE</varname> is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1945 a number, and <varname>CYGDAT_LIBC_STDIO_DEFAULT_CONSOLE</varname> is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1946 a string corresponding to a device name. A few options like
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1947 <varname>CYGDAT_UITRON_TASK_EXTERNS</varname> can get very
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1948 complicated. &CDL; has to cope with this variety, and define the exact
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1949 behavior of the system in terms of constraints and build-time
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1950 consequences.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1951 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1952 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1953 In &CDL; the value of an option consists of two parts. There is a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1954 boolean part, controlling whether or not the option is enabled. There
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1955 is also a data part, providing additional information. For most
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1956 options one of these parts is fixed, as controlled by the option's
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1957 &flavor; property:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1958 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1959 <informaltable frame="all" colsep=1 rowsep=1 pgwide=0 tocentry=0>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1960 <tgroup cols=3 colsep=1 rowsep=1 align=left>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1961 <thead>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1962 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1963 <entry>Flavor</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1964 <entry>Enabled</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1965 <entry>Data</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1966 </row
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1967 </thead>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1968 <tbody>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1969 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1970 <entry><literal>none</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1971 <entry>Always enabled</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1972 <entry><literal>1</literal>, not modifiable</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1973 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1974 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1975 <entry><literal>bool</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1976 <entry>User-modifiable</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1977 <entry><literal>1</literal>, not modifiable</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1978 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1979 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1980 <entry><literal>data</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1981 <entry>Always enabled</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1982 <entry>User-modifiable</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1983 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1984 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1985 <entry><literal>booldata</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1986 <entry>User-modifiable</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1987 <entry>User-modifiable</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1988 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1989 </tbody>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1990 </tgroup>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1991 </informaltable>
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 The effects of the boolean and data parts are as follows:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1994 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1995 <orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1996 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1997 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1998 If an option is disabled, in other words if the boolean part is false,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1999 then any references to that option in &CDL; expressions will evaluate
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2000 to <literal>0</literal>. This is the same behavior as for inactive
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2001 options. The data part is not relevant. The <literal>none</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2002 and <literal>data</literal> flavors specify that the option is always
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2003 enabled, in which case this rule is not applicable.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2004 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2005 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2006 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2007 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2008 If an option is enabled then any references to that option in &CDL;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2009 expressions will evaluate to the option's data part. For two of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2010 flavors, <literal>none</literal> and <literal>bool</literal>, this
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2011 data part is fixed to the constant <literal>1</literal> which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2012 generally has the expected result.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2013 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2014 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2015 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2016 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2017 If a component or package is disabled then all sub-components and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2018 options immediately below it in the hierarchy are inactive. By a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2019 process of recursion this will affect all the nodes in the subtree.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2020 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2021 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2022 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2023 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2024 If an option is disabled then it can impose no constraints on the rest
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2025 of the configuration, in particular &requires; and &legal-values;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2026 properties will be ignored. If an option is enabled then its
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2027 constraints should be satisfied, or the component framework will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2028 report various conflicts. Note that the &legal-values; constraint only
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2029 applies to the data part of the option's value, so it is only useful
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2030 with the <literal>data</literal> and <literal>booldata</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2031 flavors. Options with the <literal>none</literal> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2032 <literal>data</literal> flavors are always enabled so their
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2033 constraints always have to be satisfied (assuming the option is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2034 active).
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2035 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2036 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2037 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2038 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2039 If an option is disabled then it has no direct consequences at
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2040 build-time: no <literal>#define</literal> will be generated, no files
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2041 will get compiled, and so on. If an option is active and enabled then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2042 all the consequences take effect. The option name and data part are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2043 used to generate the <literal>#define</literal> in the appropriate
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2044 configuration header file, subject to various properties such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2045 &no-define;, but the data part has no other effects on the build
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2046 system.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2047 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2048 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2049 </orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2050 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2051 By default all options and components have the <literal>bool</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2052 flavor: most options are boolean in nature, so making this the default
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2053 allows for slightly more compact &CDL; scripts. Packages have the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2054 <literal>booldata</literal> flavor, where the data part always
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2055 corresponds to the version of the package that is loaded into the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2056 configuration: changing this value corresponds to unloading the old
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2057 version and loading in a different one.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2058 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2059
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2060 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2061 <title>&CDL; Flavors</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2062 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2063 The concept of &CDL; flavors tends to result in various discussions
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2064 about why it is unnecessarily complicated, and would it not have been
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2065 easier to do&nbsp;&hellip; However there are very good reasons why CDL
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2066 works the way it does.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2067 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2068 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2069 The first common suggestion is that there is no need to have separate
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2070 flavors <literal>bool</literal>, <literal>data</literal>, and so on. A
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2071 boolean option could just be handled as a data option with legal
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2072 values <literal>0</literal> and <literal>1</literal>. The counter
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2073 arguments are as follows:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2074 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2075 <orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2076 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2077 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2078 It would actually make &CDL; scripts more verbose. By default all
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2079 options and components have the <literal>bool</literal> flavor, since
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2080 most options are boolean in nature. Without a <literal>bool</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2081 flavor it would be necessary to indicate explicitly what the legal
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2082 values are somehow, e.g. with a &legal-values; property.
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 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2085 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2086 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2087 The boolean part of an option's value has a very different effect from
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2088 the data part. If an option is disabled then it has no consequences at
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2089 build time, and can impose no constraints. A <literal>data</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2090 option always has consequences and can impose constraints. To get the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2091 desired effect it would be necessary to add &CDL; data indicating that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2092 a value of <literal>0</literal> should be treated specially. Arguably
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2093 this could be made built-in default behavior, although that would
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2094 complicate options where <literal>0</literal> is a perfectly legal
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2095 number, for example
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2096 <varname>CYGNUM_LIBC_TIME_STD_DEFAULT_OFFSET</varname>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2097 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2098 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2099 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2100 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2101 There would no replacement for a <literal>booldata</literal> option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2102 for which <literal>0</literal> is a valid value. Again some additional
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2103 &CDL; syntax would be needed to express such a concept.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2104 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2105 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2106 </orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2107 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2108 Although initially it may seem confusing that an option's value has
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2109 both a boolean and a data part, it is an accurate reflection of how
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2110 configuration options actually work. The various alternatives would
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2111 all make it harder to write &CDL; scripts.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2112 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2113 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2114 The next common suggestion is that the data part of a value should be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2115 typed in much the same way as C or C++ data types. For example it
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2116 should be possible to describe
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2117 <varname>CYGNUM_LIBC_STDIO_BUFSIZE</varname> as an integer value,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2118 rather than imposing &legal-values; constraints. Again there are very
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2119 good reasons why this approach was not taken:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2120 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2121 <orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2122 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2123 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2124 The possible legal values for an integer are rarely correct for a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2125 &CDL; option. A constraint such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2126 <literal>1&nbsp;to&nbsp;0x7fffffff</literal> is a bit more accurate,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2127 although if this option indicates a buffer size it is still not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2128 particularly good&nbsp;&mdash; very few targets will have enough
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2129 memory for such a buffer. Forcing &CDL; writers to list the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2130 &legal-values; constraints explicitly should make them think a bit
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2131 more about what values are actually sensible. For example
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2132 <varname>CYGNUM_LIBC_TIME_DST_DEFAULT_OFFSET</varname> has legal
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2133 values in the range <literal>-90000&nbsp;to&nbsp;90000</literal>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2134 which helps the user to set a sensible value.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2135 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2136 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2137 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2138 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2139 Not all options correspond to simple data types such as integers.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2140 <varname>CYGDAT_LIBC_STDIO_DEFAULT_CONSOLE</varname> is a C string,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2141 and would have to be expressed using something like
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2142 <literal>char&nbsp;[]</literal>. This introduces plenty of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2143 opportunities for confusion, especially since square brackets may get
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2144 processed by the &Tcl; interpreter for command substitution.
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 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2147 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2148 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2149 Some configuration options can get very complicated indeed, for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2150 example the default value of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2151 <varname>CYGDAT_UITRON_TASK_INITIALIZERS</varname> is:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2152 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2153 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2154 CYG_UIT_TASK( "t1", 1, task1, &amp;stack1, CYGNUM_UITRON_STACK_SIZE ), \
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2155 CYG_UIT_TASK( "t2", 2, task2, &amp;stack2, CYGNUM_UITRON_STACK_SIZE ), \
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2156 CYG_UIT_TASK( "t3", 3, task3, &amp;stack3, CYGNUM_UITRON_STACK_SIZE ), \
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2157 CYG_UIT_TASK( "t4", 4, task4, &amp;stack4, CYGNUM_UITRON_STACK_SIZE )
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2158 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2159 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2160 This would require &CDL; knowing about C macros, structures, arrays,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2161 static initializers, and so on. Adding such detailed knowledge about
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2162 the C language to the component framework is inappropriate.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2163 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2164 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2165 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2166 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2167 &CDL; needs to be usable with languages other than C. At present this
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2168 includes C++, in future it may include languages such as Java. Each
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2169 language adds new data types and related complications, for example
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2170 C++ classes and inheritance. Making &CDL; support a union of all data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2171 types in all possible languages is not sensible.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2172 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2173 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2174 </orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2175 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2176 The &CDL; approach of treating all data as a sequence of characters,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2177 possibly constrained by a &legal-values; property or other means, has
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2178 the great advantage of simplicity. It also fits in with the &Tcl;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2179 language that underlies &CDL;.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2180 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2181 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2182
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2183 </sect3>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2184
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2185 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2186 <!-- {{{ Examples -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2187
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2188 <sect3 id="language.values.value.examples">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2189 <title>Some Examples</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2190
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2191 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2192 The following excerpt from the C library's &CDL; scripts can be used
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2193 to illustrate how values and flavors work in practice:
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 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2196 cdl_component CYGPKG_LIBC_RAND {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2197 flavor none
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2198 compile stdlib/rand.cxx
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2199
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2200 cdl_option CYGSEM_LIBC_PER_THREAD_RAND {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2201 requires CYGVAR_KERNEL_THREADS_DATA
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2202 default_value 0
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2203 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2204
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2205 cdl_option CYGNUM_LIBC_RAND_SEED {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2206 flavor data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2207 legal_values 0 to 0x7fffffff
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2208 default_value 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2209 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2211 cdl_option CYGNUM_LIBC_RAND_TRACE_LEVEL {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2212 flavor data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2213 legal_values 0 to 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2214 default_value 0
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2215 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2216 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2217 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2218 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2219 If the application does not require any C library functionality then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2220 it is possible to have a configuration where the C library is not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2221 loaded. This can be achieved by starting with the minimal template, or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2222 by starting with another template such as the default one and then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2223 explicitly unloading the C library package. If this package is not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2224 loaded then any references to the <varname>CYGPKG_LIBC_RAND</varname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2225 component or any of its options will have a value of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2226 <literal>0</literal> for the purposes of expression evaluation. No
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2227 <literal>#define's</literal> will be generated for the component or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2228 any of its options, and the file <filename>stdlib/rand.cxx</filename>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2229 will not get compiled. There is nothing special about the C library
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2230 here, exactly the same would apply for say a device driver that does
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2231 not correspond to any of the devices on the target hardware.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2232 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2233 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2234 Assuming the C library is loaded, the next thing to consider is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2235 whether or not the component and its options are active. The component
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2236 is layered immediately below the C library package itself, so if the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2237 package is loaded then it is safe to assume that the package is also
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2238 enabled. Therefore the parent of <varname>CYGPKG_LIBC_RAND</varname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2239 is active and enabled, and in the absence of any &active-if;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2240 properties <varname>CYGPKG_LIBC_RAND</varname> will be active as well.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2241 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2242 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2243 The component <varname>CYGPKG_LIBC_RAND</varname> has the flavor
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2244 <literal>none</literal>. This means the component cannot be disabled.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2245 Therefore all the options in this component have an active and enabled
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2246 parent, and in the absence of any &active-if; properties they are all
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2247 active as well.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2248 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2249 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2250 The component's flavor <literal>none</literal> serves to group
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2251 together all of the configuration options related to random number
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2252 generation. This is particularly useful in the context of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2253 graphical configuration tool, but it also helps when it comes to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2254 naming the options: all of the options begin with
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2255 <literal>CYGxxx_LIBC_RAND</literal>, giving a clear hint about both
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2256 the package and the component within that package. The flavor means
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2257 that the component is always enabled and has the value
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2258 <literal>1</literal> for the purposes of expression evaluation. There
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2259 will always be a single <literal>#define</literal> of the form:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2260 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2261 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2262 #define CYGPKG_LIBC_RAND 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2263 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2264 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2265 In addition the file <filename>stdlib/rand.cxx</filename> will always
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2266 get built. If the component had the default <literal>bool</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2267 flavor then users would be able to disable the whole component,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2268 and one less file would need to be built. However random number
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2269 generation is relatively simple, so the impact on eCos build times are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2270 small. Furthermore by default the code has no dependencies on other
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2271 parts of the system, so compiling the code has no unexpected side
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2272 effects. Even if it was possible to disable the component, the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2273 sensible default for most applications would still leave it enabled.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2274 The net result is that the flavor <literal>none</literal> is probably
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2275 the most sensible one for this component. For other components the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2276 default <literal>bool</literal> flavor or one of the other flavors
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2277 might be more appropriate.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2278 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2279 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2280 Next consider option <varname>CYGSEM_LIBC_PER_THREAD_RAND</varname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2281 which can be used to get a per-thread random number seed, possibly
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2282 useful if the application needs a consistent sequence of random
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2283 numbers. In the absence of a &flavor; property this option will be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2284 boolean, and the &default-value; property means that it is disabled by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2285 default&nbsp;&mdash; reasonable since few applications need this
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2286 particular functionality, and it does impose a constraint on the rest
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2287 of the system. If the option is left disabled then no
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2288 <literal>#define</literal> will be generated, and if there were any
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2289 &compile; or similar properties these would not take effect. If the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2290 option is enabled then a <literal>#define</literal> will be generated,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2291 using the option's data part which is fixed at <literal>1</literal>:
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 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2294 #define CYGSEM_LIBC_PER_THREAD_RAND 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2295 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2296 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2297 The <varname>CYGSEM_LIBC_PER_THREAD_RAND</varname> option has a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2298 &requires; constraint on
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2299 <varname>CYGVAR_KERNEL_THREADS_DATA</varname>. If the C library option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2300 is enabled then the constraint should be satisfied, or else the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2301 configuration contains a conflict. If the configuration does not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2302 include the kernel package then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2303 <varname>CYGVAR_KERNEL_THREADS_DATA</varname> will evaluate to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2304 <literal>0</literal> and the constraint is not satisfied. Similarly if
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2305 the option is inactive or disabled the constraint will not be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2306 satisfied.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2307 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2308 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2309 <varname>CYGNUM_LIBC_RAND_SEED</varname> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2310 <varname>CYGNUM_LIBC_RAND_TRACE_LEVEL</varname> both have the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2311 <literal>data</literal> flavor, so they are always enabled and the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2312 component framework will generate appropriate
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2313 <literal>#define's</literal>:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2314 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2315 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2316 #define CYGNUM_LIBC_RAND_SEED 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2317 #define CYGNUM_LIBC_RAND_SEED_1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2318 #define CYGNUM_LIBC_RAND_TRACE_LEVEL 0
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2319 #define CYGNUM_LIBC_RAND_TRACE_LEVEL_0
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2320 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2321 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2322 Neither option has a &compile; or similar property, but any such
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2323 properties would take effect. Any references to these options in &CDL;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2324 expressions would evaluate to the data part, so a hypothetical
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2325 constraint of the form
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2326 <literal>{&nbsp;requires&nbsp;CYGNUM_LIBC_RAND_SEED&nbsp;&gt;&nbsp;42&nbsp;}</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2327 would not be satisfied with the default values. Both options use a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2328 simple constant for the &default-value; expression. It would be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2329 possible to use a more complicated expression, for example the default
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2330 for <varname>CYGNUM_LIBC_RAND_TRACE_LEVEL</varname> could be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2331 determined from some global debugging option or from a debugging
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2332 option that applies to the C library as a whole. Both options also
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2333 have a &legal-values; constraint, which must be satisfied since the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2334 options are active and enabled.
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 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2337 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2338 The value <literal>0</literal> is legal for both
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2339 <varname>CYGNUM_LIBC_RAND_SEED</varname> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2340 <varname>CYGNUM_LIBC_RAND_TRACE_LEVEL</varname>, so in a &CDL;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2341 expression there is no easy way of distinguishing between the options
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2342 being absent or having that particular value. This will be addressed
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2343 by future enhancements to the expression syntax.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2344 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2345 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2346
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2347 </sect3>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2348
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2349 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2350 </sect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2351
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2352 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2353 <!-- {{{ Expressions -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2354
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2355 <sect2 id="language.expression">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2356 <title>Ordinary Expressions</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2357
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2358 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2359 Expressions in &CDL; follow a conventional syntax, for example:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2360 </para>
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 default_value CYGGLO_CODESIZE &gt; CYGGLO_SPEED
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2363 default_value { (CYG_HAL_STARTUP == "RAM" &&
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2364 !CYGDBG_HAL_DEBUG_GDB_INCLUDE_STUBS &&
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2365 !CYGINT_HAL_USE_ROM_MONITOR_UNSUPPORTED &&
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2366 !CYGSEM_HAL_POWERPC_COPY_VECTORS) ? 1 : 0 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2367 default_value { "\"/dev/ser0\"" }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2368 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2369 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2370 However there is a complication in that the various arguments to a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2371 &default-value; property will first get processed by a &Tcl;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2372 interpreter, so special characters like quotes and square brackets may
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2373 get processed. Such problems can be avoided by enclosing non-trivial
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2374 expressions in braces, as in the second example above. The way
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2375 expression parsing actually works is as follows:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2376 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2377 <orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2378 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2379 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2380 The &Tcl; interpreter splits the line or lines into a command and its
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2381 arguments. In the first &default-value; expression above the command
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2382 is <literal>default_value</literal> and there are three arguments,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2383 <literal>CYGGLO_CODESIZE</literal>, <literal>&gt;</literal> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2384 <literal>CYGGLO_SPEED</literal>. In the second and third examples
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2385 there is just one argument, courtesy of the braces.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2386 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2387 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2388 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2389 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2390 Next option processing takes place, so any initial arguments that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2391 begin with a hyphen will be interpreted as options. This can cause
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2392 problems if the expression involves a negative number, so the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2393 special argument <literal>--</literal> can be used to prevent option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2394 processing on the subsequent arguments.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2395 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2396 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2397 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2398 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2399 All of the arguments are now concatenated, with a single space in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2400 between each one. Hence the following two expressions are equivalent,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2401 even though they will have been processed differently up to this point.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2402 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2403 <programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2404 default_value CYGGLO_CODESIZE &gt; CYGGLO_SPEED
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2405 default_value {CYGGLO_CODESIZE &gt; CYGGLO_SPEED}
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2406 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2407 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2408 <listitem>
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 expression parsing code now has a single string to process.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2411 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2412 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2413 </orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2414 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2415 &CDL; expressions consist of four types of element: references to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2416 configuration options, constant strings, integers, and floating point
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2417 numbers. These are combined using a conventional set of operators: the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2418 unary operators <literal>-</literal>, <literal>~</literal> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2419 <literal>!</literal>; the arithmetic operators <literal>+</literal>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2420 <literal>-</literal>, <literal>*</literal>, <literal>/</literal> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2421 <literal>%</literal>; the shift operators <literal>&lt;&lt;</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2422 and <literal>&gt;&gt;</literal>; the comparison operators
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2423 <literal>==</literal>, <literal>!=</literal>, <literal>&lt;</literal>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2424 <literal>&lt;=</literal>, <literal>&gt;</literal> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2425 <literal>&gt;=</literal>; the bitwise operators
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2426 <literal>&amp;</literal>, <literal>^</literal> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2427 <literal>|</literal>; the logical operators <literal>&&</literal> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2428 <literal>||</literal>; the string concatenation operator
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2429 <literal>.</literal>; and the ternary conditional operator
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2430 <literal>A&nbsp;?&nbsp;B&nbsp;:&nbsp;C</literal>. There is also support for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2431 some less widely available operators for logical equivalence and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2432 implication, and for a set of function-style operations. Bracketed
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2433 sub-expressions are supported, and the operators have the usual
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2434 precedence:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2435 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2436 <informaltable frame="all" pgwide=0 colsep=1 rowsep=1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2437 <tgroup cols=3 align="left" colsep=1 rowsep=1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2438 <colspec colnum=1 align="center">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2439 <colspec colnum=2 align="center">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2440 <colspec colnum=3 align="center">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2441 <thead>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2442 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2443 <entry>Priority</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2444 <entry>Operators</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2445 <entry>Category</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2446 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2447 </thead>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2448 <tbody>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2449 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2450 <entry>16</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2451 <entry>references, constants</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2452 <entry>basic elements</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2453 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2454 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2455 <entry>15</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2456 <entry><literal>f(a, b, c)</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2457 <entry>function calls</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2458 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2459 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2460 <entry>14</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2461 <entry><literal>~</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2462 <entry>bitwise not</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2463 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2464 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2465 <entry>14</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2466 <entry><literal>!</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2467 <entry>logical not</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2468 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2469 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2470 <entry>14</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2471 <entry><literal>-</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2472 <entry>arithmetic negation</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2473 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2474 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2475 <entry>13</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2476 <entry><literal>* / %</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2477 <entry>multiplicative arithmetic</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2478 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2479 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2480 <entry>12</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2481 <entry><literal>+ - .</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2482 <entry>additive arithmetic and string concatenation</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2483 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2484 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2485 <entry>11</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2486 <entry><literal>&lt;&lt; &gt;&gt;</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2487 <entry>bitwise shifts</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2488 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2489 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2490 <entry>10</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2491 <entry><literal>&lt;= &lt; &gt; &gt;=</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2492 <entry>inequality</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2493 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2494 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2495 <entry>9</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2496 <entry><literal>== !=</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2497 <entry>comparison</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2498 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2499 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2500 <entry>8</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2501 <entry><literal>&</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2502 <entry>bitwise and</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2503 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2504 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2505 <entry>7</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2506 <entry><literal>^</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2507 <entry>bitwise xor</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2508 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2509 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2510 <entry>6</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2511 <entry><literal>|</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2512 <entry>bitwise or</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2513 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2514 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2515 <entry>5</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2516 <entry><literal>&&</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2517 <entry>logical and</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2518 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2519 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2520 <entry>4</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2521 <entry><literal>||</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2522 <entry>logical or</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2523 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2524 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2525 <entry>3</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2526 <entry><literal>xor, eqv</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2527 <entry>logical equivalance</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2528 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2529 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2530 <entry>2</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2531 <entry><literal>implies</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2532 <entry>logical implication</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2533 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2534 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2535 <entry>1</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2536 <entry><literal>? :</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2537 <entry>conditional</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2538 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2539 </tbody>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2540 </tgroup>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2541 </informaltable>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2542
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2543 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2544 Function calls have the usual format of a name, an opening bracket,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2545 one or more arguments separated by commas, and a closing bracket. For
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2546 example:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2547 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2548 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2549 requires { !is_substr(CYGBLD_GLOBAL_CFLAGS, " -fno-rtti") }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2550 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2551 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2552 Functions will differ in the number of arguments and may impose
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2553 restrictions on some or all of their arguments. For example it may be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2554 necessary for the first argument to be a reference to a configuration
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2555 option. The available functions are described in <xref
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2556 linkend="language.functions">.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2557 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2558 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2559 The logical <literal>xor</literal> operator evaluates to true if
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2560 either the left hand side or the right hand side but not both evaluate
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2561 to true The logical <literal>eqv</literal> operator evaluates to true
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2562 if both the left and right hand sides evaluate to true, or if both
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2563 evaluate to false. The <literal>implies</literal> operator evaluates
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2564 to true either if the left hand side is false or if the right hand
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2565 side is true, in other words <literal>A&nbsp;implies&nbsp;B</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2566 has the same meaning as <literal>!A&nbsp;||&nbsp;B</literal>. An
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2567 example use would be:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2568 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2569 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2570 requires { is_active(CYGNUM_LIBC_MAIN_DEFAULT_STACK_SIZE) implies
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2571 (CYGNUM_LIBC_MAIN_DEFAULT_STACK_SIZE >= (16 * 1024)) }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2572 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2573 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2574 This constraint would be satisfied if either the support for a main
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2575 stack size is disabled, or if that stack is at least 16K. However if
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2576 such a stack were in use but was too small, a conflict would be raised.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2577 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2578 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2579 A valid &CDL; identifier in an expression, for example
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2580 <varname>CYGGLO_SPEED</varname>, will be interpreted as a reference to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2581 a configuration option by that name. The option does not have to be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2582 loaded into the current configuration. When the component framework
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2583 evaluates the expression it will substitute in a suitable value that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2584 depends on whether or not the option is loaded, active, and enabled.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2585 The exact rules are described in <xref
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2586 linkend="language.values.value">.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2587 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2588 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2589 A constant string is any sequence of characters enclosed in quotes.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2590 Care has to be taken that these quotes are not stripped off by the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2591 &Tcl; interpreter before the &CDL; expression parser sees them.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2592 Consider the following:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2593 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2594 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2595 default_value "RAM"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2596 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2597 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2598 The quote marks will be stripped before the &CDL; expression parser
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2599 sees the data, so the expression will be interpreted as a reference to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2600 a configuration option <varname>RAM</varname>. There is unlikely to be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2601 such an option, so the actual default value will be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2602 <literal>0</literal>. Careful use of braces or other &Tcl; quoting
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2603 mechanisms can be used to avoid such problems.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2604 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2605 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2606 String constants consist of the data inside the quotes. If the data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2607 itself needs to contain quote characters then appropriate quoting is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2608 again necessary, for example:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2609 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2610 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2611 default_value { "\"/dev/ser0\"" }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2612 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2613 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2614 An integer constant consists of a sequence of digits, optionally
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2615 preceeded with the unary <literal>+</literal> or <literal>-</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2616 operators. As usual the sequence <literal>0x</literal> or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2617 <literal>0X</literal> can be used for hexadecimal data, and a leading
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2618 <literal>0</literal> indicates octal data. Internally the component
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2619 framework uses 64-bit arithmetic for integer data. If a constant is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2620 too large then double precision arithmetic will be used instead.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2621 Traditional syntax is also used for double precision numbers, for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2622 example <literal>3.141592</literal> or <literal>-3E6</literal>.
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 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2625 Of course this is not completely accurate: &CDL; is not a typed
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2626 language, all data is treated as if it were a string. For example the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2627 following two lines are equivalent:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2628 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2629 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2630 requires CYGNUM_UITRON_SEMAS > 10
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2631 requires { CYGNUM_UITRON_SEMAS > "10" }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2632 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2633 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2634 When an expression gets evaluated the operators will attempt
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2635 appropriate conversions. The <literal>&gt;</literal> comparison
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2636 operator can be used on either integer or double precision numbers, so
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2637 it will begin by attempting a string to integer conversion of both
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2638 operands. If that fails it will attempt string to double conversions.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2639 If that fails as well then the component framework will report a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2640 conflict, an evaluation exception. If the conversions from string to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2641 integer are successful then the result will be either the string
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2642 <literal>0</literal> or the string <literal>1</literal>, both of which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2643 can be converted to integers or doubles as required.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2644 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2645 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2646 It is worth noting that the expression
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2647 <literal>CYGNUM_UITRON_SEMAS&nbsp;&gt;10</literal> is not ambiguous.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2648 &CDL; identifiers can never begin with a digit, so it is not possible
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2649 for <literal>10</literal> to be misinterpreted as a reference to an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2650 identifier instead of as a string.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2651 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2652 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2653 Of course the implementation is slightly different again. The &CDL;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2654 language definition is such that all data is treated as if it were a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2655 string, with conversions to integer, double or boolean as and when
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2656 required. The implementation is allowed to avoid conversions until
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2657 they are necessary. For example, given
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2658 <literal>CYGNUM_UITRON_SEMAS&nbsp;&gt;&nbsp;10</literal> the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2659 expression parsing code will perform an immediate conversion from
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2660 string to integer, storing the integer representation, and there is no
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2661 need for a conversion by the comparison operator when the expression
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2662 gets evaluated. Given
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2663 <literal>{&nbsp;CYGNUM_UITRON_SEMAS&nbsp;&gt;&nbsp;"10"&nbsp;}</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2664 the parsing code will store the string representation and a conversion
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2665 happens the first time the expression is evaluated. All of this is an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2666 implementation detail, and does not affect the semantics of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2667 language.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2668 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2669 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2670 Different operators have different requirements, for example the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2671 bitwise or operator only makes sense if both operands have an integer
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2672 representation. For operators which can work with either integer or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2673 double precision numbers, integer arithmetic will be preferred.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2674 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2675 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2676 The following operators only accept integer operands:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2677 unary <literal>~</literal> (bitwise not), the shift operators
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2678 <literal>&lt;&lt;</literal> and <literal>&gt;&gt;</literal>, and the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2679 bitwise operators <literal>&</literal>, <literal>|</literal> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2680 <literal>^</literal>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2681 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2682 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2683 The following operators will attempt integer arithmetic first, then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2684 double precision arithmetic: unary <literal>-</literal>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2685 the arithmetic operators <literal>+</literal>, <literal>-</literal>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2686 <literal>*</literal>, <literal>/</literal>, and <literal>%</literal>;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2687 and the comparision operators <literal>&lt;</literal>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2688 <literal>&lt;=</literal>, <literal>&gt;</literal> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2689 <literal>&gt;=</literal>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2690 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2691 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2692 The equality <literal>==</literal> and inequality
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2693 <literal>!=</literal> operators will first attempt integer conversion
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2694 and comparison. If that fails then double precision will be attempted
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2695 (although arguably using these operators on double precision data is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2696 not sensible). As a last resort string comparison will be used.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2697 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2698 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2699 The operators <literal>!</literal>, <literal>&&</literal> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2700 <literal>||</literal> all work with boolean data. Any string that can
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2701 be converted to the integer <literal>0</literal> or the double
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2702 <literal>0.0</literal> is treated as false, as is the empty string or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2703 the constant string <literal>false</literal>. Anything else is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2704 interpreted as true. The result is either <literal>0</literal> or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2705 <literal>1</literal>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2706 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2707 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2708 The conditional operator <literal>?&nbsp;:</literal> will interpret
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2709 its first operand as a boolean. It does not perform any processing on
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2710 the second or third operands.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2711 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2712 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2713 In practice it is rarely necessary to worry about any of these
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2714 details. In nearly every case &CDL; expressions just work as expected,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2715 and there is no need to understand the full details.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2716 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2717
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2718 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2719 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2720 The current expression syntax does not meet all the needs of component
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2721 writers. Some future enhancements will definitely be made, others are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2722 more controversial. The list includes the following:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2723 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2724 <orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2725 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2726 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2727 An option's value is determined by several different factors: whether
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2728 or not it is loaded, whether or not it is active, whether or not it is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2729 enabled, and the data part. Currently there is no way of querying
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2730 these individually. This is very significant in the context of options
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2731 with the <literal>bool</literal> or <literal>booldata</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2732 flavors, because there is no way of distinguishing between the option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2733 being absent/inactive/disabled or it being enabled with a data field
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2734 of <literal>0</literal>. There should be unary operators that allow
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2735 any of the factors to be checked.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2736 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2737 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2738 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2739 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2740 Only the <literal>==</literal> and <literal>!=</literal> operators can
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2741 be used for string data. More string-related facilities are needed.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2742 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2743 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2744 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2745 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2746 An implies operator would be useful for many goal expression, where
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2747 <literal>A&nbsp;implies&nbsp;B</literal> is equivalent to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2748 <literal>!A&nbsp;||B</literal>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2749 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2750 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2751 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2752 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2753 Similarly there is inadequate support for lists. On occasion it would
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2754 be useful to write expressions involving say the list of implementors
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2755 of a given CDL interface, for example a sensible default value could
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2756 be the first implementor. Associated with this is a need for an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2757 indirection operator.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2758 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2759 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2760 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2761 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2762 Arguably extending the basic &CDL; expression syntax with lots of new
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2763 operators is unnecessary, instead expressions should just support
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2764 &Tcl; command substitution and then component writers could escape
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2765 into &Tcl; scripts for complicated operations. This has some major
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2766 disadvantages. First, the inference engine would no longer have any
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2767 sensible way of interpreting an expression to resolve a conflict.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2768 Second, the component framework's value propagation code keeps track
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2769 of which options get referenced in which expressions and avoids
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2770 unnecessary re-evaluation of expressions; if expressions can involve
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2771 arbitrary &Tcl; code then there is no simple way to eliminate
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2772 unnecessary recalculations, with a potentially major impact on
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2773 performance.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2774 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2775 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2776 </orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2777 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2778
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2779 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2780 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2781 The current implementation of the component framework uses 64 bit
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2782 arithmetic on all host platforms. Although this is adequate for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2783 current target architectures, it may cause problems in future. At some
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2784 stage it is likely that an arbitrary precision integer arithmetic
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2785 package will be used instead.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2786 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2787 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2788
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2789 </sect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2790
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2791 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2792 <!-- {{{ Functions -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2793
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2794 <sect2 id="language.functions">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2795 <title>Functions</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2796
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2797 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2798 CDL expressions can contain calls to a set of built-in functions
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2799 using the usual syntax, for example;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2800 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2801 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2802 requires { !is_substr(CYGBLD_GLOBAL_CFLAGS, "-fno-rtti") }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2803 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2804 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2805 The available function calls are as follows:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2806 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2807
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2808 <variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2809
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2810 <!-- {{{ get_data() -->
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 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2813 <term><literal>get_data(option)</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2814 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2815 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2816 This function can be used to obtain just the data part of a loaded
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2817 configuration option, ignoring other factors such as whether or not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2818 the option is active and enabled. It takes a single argument which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2819 should be the name of a configuration option. If the specified option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2820 is not loaded in the current configuration then the function returns
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2821 0, otherwise it returns the data part. Typically this function will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2822 only be used in conjunction with <function>is_active</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2823 <function>is_enabled</function> for fine-grained control over the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2824 various factors that make up an option's value.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2825 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2826 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2827 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2828
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2829 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2830 <!-- {{{ is_active() -->
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 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2833 <term><literal>is_active(option)</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2834 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2835 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2836 This function can be used to determine whether or not a particular
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2837 configuration option is active. It takes a single argument which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2838 should be the name of an option, and returns a boolean. If the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2839 specified option is not loaded then the function will return false.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2840 Otherwise it will consider the state of the option's parents and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2841 evaluate any &active-if; properties, and return the option's current
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2842 active state. A typical use might be:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2843 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2844 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2845 requires { is_active(CYGNUM_LIBC_MAIN_DEFAULT_STACK_SIZE) implies
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2846 (CYGNUM_LIBC_MAIN_DEFAULT_STACK_SIZE >= (16 * 1024)) }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2847 </programlisting>
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 In other words either the specified configuration option must be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2850 inactive, for example because the current application does not use
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2851 any related C library or POSIX functionality, or the stack size must
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2852 be at least 16K.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2853 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2854 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2855 The configuration system's inference engine can attempt to satisfy
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2856 constraints involving <function>is_active</function> in various
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2857 different ways, for example by enabling or disabling parent
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2858 components, or by examining &active-if; properties and manipulating
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2859 terms in the associated expressions.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2860 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2861 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2862 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2863
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2864 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2865 <!-- {{{ is_enabled() -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2866
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2867 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2868 <term><literal>is_enabled(option)</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2869 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2870 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2871 This function can be used to determine whether or not a particular
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2872 configuration option is enabled. It takes a single argument which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2873 should be the name of an option, and returns a boolean. If the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2874 specified option is not loaded then the function will return false.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2875 Otherwise it will return the current boolean part of the option's
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2876 value. The option's active or inactive state is ignored. Typically
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2877 this function will be used in conjunction with
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2878 <function>is_active</function> and possibly
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2879 <function>get_data</function> to provide fine-grained control over the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2880 various factors that make up an option's value.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2881 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2882 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2883 </varlistentry>
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 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2886 <!-- {{{ is_loaded() -->
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 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2889 <term><literal>is_loaded(option)</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2890 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2891 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2892 This function can be used to determine whether or not a particular
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2893 configuration option is loaded. It takes a single argument which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2894 should be the name of an option, and returns a boolean. If the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2895 argument is a package then the <function>is_loaded</function> function
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2896 provides little or no extra information, for example the following two
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2897 constraints are usually equivalent:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2898 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2899 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2900 requires { CYGPKG_KERNEL }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2901 requires { is_loaded(CYGPKG_KERNEL) }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2902 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2903 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2904 However if the specified package is loaded but re-parented below a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2905 disabled component, or inactive as a result of an &active-if;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2906 property, then the first constraint would not be satisfied but the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2907 second constraint would. In other words the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2908 <function>is_loaded</function> makes it possible to consider in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2909 isolation one of the factors that are considered when CDL expressions
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2910 are evaluated.
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 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2913 The configuration system's inference engine will not automatically
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2914 load or unload packages to satisfy <function>is_loaded</function>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2915 constraints.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2916 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2917 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2918 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2919
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2920 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2921 <!-- {{{ is_substr() -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2922
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2923 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2924 <term><literal>is_substr(haystack,&nbsp;needle)</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2925 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2926 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2927 This can be used to check whether or not a particular string is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2928 present in another string. It is used mainly for manipulating compiler
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2929 flags. The function takes two arguments, both of which can be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2930 arbitrary expressions, and returns a boolean.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2931 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2932 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2933 <function>is_substr</function> has some understanding of word
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2934 boundaries. If the second argument starts with a space character then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2935 that will match either a real space or the start of the string.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2936 Similarly if the second argument ends with a space character then that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2937 will match a real space or the end of the string. For example, all of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2938 the following conditions are satisfied:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2939 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2940 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2941 is_substr("abracadabra", "abra")
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2942 is_substr("abracadabra", " abra")
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2943 is_substr("hocus pocus", " pocus")
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2944 is_substr("abracadabra", "abra ")
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2945 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2946 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2947 The first is an exact match. The second is a match because the leading
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2948 space matches the start of the string. The third is an exact match,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2949 with the leading space matching an actual space. The fourth is a match
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2950 because the trailing space matches the end of the string. However, the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2951 following condition is not satisfied.
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 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2954 is_substr("abracadabra", " abra ")
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2955 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2956 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2957 This fails to match at the start of the string because the trailing
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2958 space is not matched by either a real space or the end of the string.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2959 Similarly it fails to match at the end of the string.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2960 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2961 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2962 If a constraint involving <function>is_substr</function> is not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2963 satisfied and the first argument is a reference to a configuration
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2964 option, the inference engine will attempt to modify that option's
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2965 value. This can be achieved either by appending the second argument to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2966 the current value, or by removing all occurrences of that argument
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2967 from the current value.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2968 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2969 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2970 requires { !is_substr(CYGBLD_GLOBAL_CFLAGS, " -fno-rtti ") }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2971 requires { is_substr(CYGBLD_GLOBAL_CFLAGS, " -frtti ") }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2972 </programlisting>
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 When data is removed the leading and trailing spaces will be left. For
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2975 example, given an initial value of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2976 <<varname>CYGBLD_GLOBAL_CFLAGS</varname> of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2977 <literal>-g&nbsp;-fno-rtti&nbsp;-O2</literal> the result will be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2978 <literal>-g&nbsp;&nbsp;-O2</literal> rather than <literal>-g-O2</literal>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2979 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2980 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2981 If exact matches are needed, the function
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2982 <function>is_xsubstr</function> can be used instead.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2983 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2984 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2985 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2986
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2987 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2988 <!-- {{{ is_xsubstr() -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2989
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2990 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2991 <term><literal>is_xsubstr(haystack,&nbsp;needle)</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2992 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2993 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2994 This function checks whether or not the pattern string is an exact
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2995 substring of the string being searched. It is similar to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2996 <function>is_substr</function> but uses exact matching only. In other
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2997 words, leading or trailing spaces have to match exactly and will not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2998 match the beginning or end of the string being searched. The function
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2999 takes two arguments, both of which can be arbitrary expressions, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3000 returns a boolean. The difference between
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3001 <function>is_substr</function> and <function>is_xsubstr</function> is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3002 illustrated by the following examples:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3003 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3004 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3005 cdl_option MAGIC {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3006 flavor data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3007 default_value { "abracadabra" }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3008 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3009 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3010 requires { is_substr(MAGIC, " abra") }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3011 requires { is_xsubstr(MAGIC, " abra") }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3012 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3013 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3014 The first goal will be satisfied because the leading space in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3015 pattern matches the beginning of the string. The second goal will not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3016 be satisfied initialy because there is no exact match, so the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3017 inference engine is likely to update the value of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3018 <varname>MAGIC</varname> to <literal>abracadabra abra</literal> which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3019 does give an exact match.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3020 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3021 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3022 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3023
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3024 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3025 <!-- {{{ version_cmp() -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3026
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3027 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3028 <term><literal>version_cmp(A,&nbsp;B)</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3029 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3030 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3031 This function is used primarily to check that a sufficiently recent
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3032 <link linkend="package.versions">version</link> of some other package
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3033 is being used. It takes two arguments, both of which can be arbitrary
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3034 expressions. In practice usually one of the arguments will be a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3035 reference to a package and the other will be a constant version
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3036 string. The return value is -1 if the first argument is a more recent
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3037 version then the second, 0 if the two arguments correspond to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3038 identical versions, and 1 if the first argument is an older version.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3039 For example the following constraint can be used to indicate that the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3040 current package depends on kernel functionality that only became
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3041 available in version 1.3:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3042 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3043 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3044 requires { version_cmp(CYGPKG_KERNEL, "v1.3") <= 0 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3045 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3046 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3047 </varlistentry>
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 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3050
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3051
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3052 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3053 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3054 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3055 At this time it is not possible to define new functions inside a CDL
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3056 script. Instead functions can only be added at the C++ level, usually
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3057 by extending libcdl itself. This is partly because there is more to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3058 CDL functions than simple evaluation: associated with most functions
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3059 is support for the inference engine, so that if a constraint involving
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3060 a function is not currently satisfied the system may be able to find a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3061 solution automatically.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3062 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3063 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3064
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3065 </sect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3066
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3067 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3068 <!-- {{{ Goal expressions -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3069
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3070 <sect2 id="language.goal-expression">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3071 <title>Goal Expressions</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3072
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3073 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3074 The arguments to certain properties, notably &requires; and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3075 &active-if;, constitute a goal expression. As with an ordinary
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3076 expression, all of the arguments get combined and then the expression
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3077 parser takes over. The same care has to be taken with constant strings
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3078 and anything else that may get processed by the Tcl interpreter, so
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3079 often a goal expression is enclosed entirely in braces and the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3080 expression parsing code sees just a single argument.
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 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3083 A goal expression is basically just a sequence of ordinary
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3084 expressions, for example:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3085 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3086 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3087 requires { CYGDBG_HAL_DEBUG_GDB_INCLUDE_STUBS
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3088 !CYGDBG_HAL_DEBUG_GDB_BREAK_SUPPORT
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3089 !CYGDBG_HAL_DEBUG_GDB_CTRLC_SUPPORT }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3090 </programlisting>
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 This consists of three separate expressions, all of which should
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3093 evaluate to a non-zero result. The same expression could be written
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3094 as:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3095 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3096 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3097 requires { CYGDBG_HAL_DEBUG_GDB_INCLUDE_STUBS &&
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3098 !CYGDBG_HAL_DEBUG_GDB_BREAK_SUPPORT &&
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3099 !CYGDBG_HAL_DEBUG_GDB_CTRLC_SUPPORT }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3100 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3101 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3102 Alternatively the following would have much the same effect:
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 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3105 requires CYGDBG_HAL_DEBUG_GDB_INCLUDE_STUBS
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3106 requires !CYGDBG_HAL_DEBUG_GDB_BREAK_SUPPORT
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3107 requires !CYGDBG_HAL_DEBUG_GDB_CTRLC_SUPPORT
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3108 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3109 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3110 Selecting between these alternatives is largely a stylistic choice.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3111 The first is slightly more concise than the others. The second is more
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3112 likely to appeal to mathematical purists. The third is more amenable
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3113 to cutting and pasting.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3114 </para>
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 The result of evaluating a goal expression is a boolean. If any part
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3117 of the goal expression evaluates to the integer <literal>0</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3118 or an equivalent string then the result is false, otherwise it is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3119 true.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3120 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3121 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3122 The term &ldquo;goal&nbsp;expression&rdquo; relates to the component
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3123 framework's inference engine: it is a description of a goal that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3124 should be satisfied for a conflict-free configuration. If a &requires;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3125 constraint is not satisfied then the inference engine will examine the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3126 goal expression: if there is some way of changing the configuration
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3127 that does not introduce new conflicts and that will cause the goal
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3128 expression to evaluate to true, the conflict can be resolved.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3129 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3130 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3131 The inference engine works with one conflict and hence one goal
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3132 expression at a time. This means that there can be slightly different
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3133 behavior if a constraint is specified using a single &requires;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3134 property or several different ones. Given the above example, suppose
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3135 that none of the three conditions are satisfied. If a single goal
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3136 expression is used then the inference engine might be able to satisfy
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3137 only two of the three parts, but since the conflict as a whole cannot
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3138 be resolved no part of the solution will be applied. Instead the user
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3139 will have to resolve the entire conflict. If three separate goal
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3140 expressions are used then the inference engine might well find
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3141 solutions to two of them, leaving less work for the user. On the other
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3142 hand, if a single goal expression is used then the inference engine
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3143 has a bit more information to work with, and it might well find a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3144 solution to the entire conflict where it would be unable to find
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3145 separate solutions for the three parts. Things can get very
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3146 complicated, and in general component writers should not worry about
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3147 the subtleties of the inference engine and how to manipulate its
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3148 behavior.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3149 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3150 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3151 It is possible to write ambiguous goal expressions, for example:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3152 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3153 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3154 requires CYGNUM_LIBC_RAND_SEED -CYGNUM_LIBC_RAND_TRACE_LEVEL &gt; 5
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3155 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3156 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3157 This could be parsed in two ways:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3158 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3159 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3160 requires ((CYGNUM_LIBC_RAND_SEED - CYGNUM_LIBC_RAND_TRACE_LEVEL) &gt; 5)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3161 requires CYGNUM_LIBC_RAND_SEED &amp;&amp; ((-CYGNUM_LIBC_RAND_TRACE_LEVEL) &gt; 5)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3162 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3163 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3164 The goal expression parsing code will always use the largest ordinary
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3165 expression for each goal, so the first interpretation will be used.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3166 In such cases it is a good idea to use brackets and avoid possible
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3167 confusion.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3168 </para>
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 </sect2>
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 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3173 <!-- {{{ List expressions -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3174
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3175 <sect2 id="language.list-expression">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3176 <title>List Expressions</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3177
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3178 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3179 The arguments to the &legal-values; property constitute a goal
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3180 expression. As with an ordinary and goal expressions, all of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3181 arguments get combined and then the expression parser takes over. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3182 same care has to be taken with constant strings and anything else that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3183 may get processed by the Tcl interpreter, so often a list expression
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3184 is enclosed entirely in braces and the expression parsing code sees
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3185 just a single argument.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3186 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3187 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3188 Most list expressions take one of two forms:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3189 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3190 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3191 legal_values &lt;expr1&gt; &lt;expr2&gt; &lt;expr3&gt; ...
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3192 legal_values &lt;expr1&gt; to &lt;expr2&gt;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3193 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3194 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3195 <literal>expr1</literal>, <literal>expr2</literal> and so on are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3196 ordinary expressions. Often these will be constants or references to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3197 calculated options in the architectural HAL package, but it is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3198 possible to use arbitrary expressions when necessary. The first syntax
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3199 indicates a list of possible values, which need not be numerical. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3200 second syntax indicates a numerical range: both sides of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3201 <literal>to</literal> must evaluate to a numerical value; if either
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3202 side involves a floating point number then any floating point number
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3203 in that range is legal; otherwise only integer values are legal;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3204 ranges are inclusive, so <literal>4</literal> is a valid value given a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3205 list expression <literal>1&nbsp;to&nbsp;</literal>; if one or both
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3206 sides of the <literal>to</literal> does not evaluate to a numerical
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3207 value then this will result in a run-time conflict. The following
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3208 examples illustrate these possibilities:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3209 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3210 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3211 legal_values { "red" "green" "blue" }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3212 legal_values 1 2 4 8 16
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3213 legal_values 1 to CYGARC_MAXINT
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3214 legal_values 1.0 to 2.0
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3215 </programlisting>
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 It is possible to combine the two syntaxes, for example:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3218 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3219 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3220 legal_values 1 2 4 to CYGARC_MAXINT -1024 -20.0 to -10
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3221 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3222 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3223 This indicates three legal values <literal>1</literal>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3224 <literal>2</literal> and <literal>-1024</literal>, one
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3225 integer range <literal>4&nbsp;to&nbsp;CYGARC_MAXINT</literal>, and one
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3226 floating point range <literal>-20.0&nbsp;to&nbsp;-10.0</literal>. In
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3227 practice such list expressions are rarely useful.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3228 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3229 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3230 The identifier <varname>to</varname> is not reserved, so it is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3231 possible to have a configuration option with that name (although it
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3232 violates every naming convention). Using that option in a list
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3233 expression may however give unexpected results.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3234 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3235 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3236 The graphical configuration tool uses the &legal-values; list
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3237 expression to determine how best to let users manipulate the option's
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3238 value. Different widgets will be appropriate for different lists, so
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3239 <literal>{&nbsp;"red"&nbsp;"green"&nbsp;"blue"&nbsp;}</literal> might
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3240 involve a pull-down option menu, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3241 <literal>1&nbsp;to&nbsp;16</literal> could involve a spinner. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3242 exact way in which &legal-values; lists get mapped on to GUI widgets
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3243 is not defined and is subject to change at any time.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3244 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3245 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3246 As with goal expressions, list expressions can be ambiguous. Consider
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3247 the following hypothetical example:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3248 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3249 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3250 legal_values CYGNUM_LIBC_RAND_SEED -CYGNUM_LIBC_RAND_TRACE_LEVEL
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3251 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3252 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3253 This could be parsed in two ways:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3254 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3255 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3256 legal_values (CYGNUM_LIBC_RAND_SEED - CYGNUM_LIBC_RAND_TRACE_LEVEL)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3257 legal_values (CYGNUM_LIBC_RAND_SEED) (-CYGNUM_LIBC_RAND_TRACE_LEVEL)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3258 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3259 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3260 Both are legal. The list expression parsing code will always use the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3261 largest ordinary expression for each element, so the first
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3262 interpretation will be used. In cases like this it is a good idea to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3263 use brackets and avoid possible confusion.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3264 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3265
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3266 </sect2>
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 </sect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3270
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3271 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3272 <!-- {{{ Interfaces -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3273
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3274 <!-- FIXME: Maybe the use of interfaces in generic drivers should be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3275 used - if only because interfaces are not really a good solution for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3276 what we need there (the generic driver cannot contain the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3277 cdl_interface and be active_if on it, since it'll result in other
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3278 packages not being able to implement the interface.) -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3279
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3280 <sect1 id="language.interface">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3281 <title>Interfaces</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3282
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 For many configurability requirements, options provide sufficient
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3285 expressive power. However there are times when a higher level of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3286 abstraction is appropriate. As an example, suppose that some package
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3287 relies on the presence of code that implements the standard kernel
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3288 scheduling interface. However the requirement is no more stringent
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3289 than this, so the constraint can be satisfied by the mlqueue
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3290 scheduler, the bitmap scheduler, or any additional schedulers that may
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3291 get implemented in future. A first attempt at expressing the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3292 dependency might be:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3293 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3294 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3295 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
3296 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3297 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3298 This constraint will work with the current release, but it is limited.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3299 Suppose there is a new release of the kernel which adds another
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3300 scheduler such as a deadline scheduler, or suppose that there is a new
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3301 third party package which adds such a scheduler. The package
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3302 containing the limited constraint would now have to be updated and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3303 another release made, with possible knock-on effects.
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 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3306 &CDL; interfaces provide an abstraction mechanism: constraints can be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3307 expressed in terms of an abstract concept, for example
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3308 &ldquo;scheduler&rdquo;, rather than specific implementations such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3309 <varname>CYGSEM_KERNEL_SCHED_MLQUEUE</varname> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3310 <varname>CYGSEM_KERNEL_SCHED_BITMAP</varname>. Basically an interface
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3311 is a calculated configuration option:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3312 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3313 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3314 cdl_interface CYGINT_KERNEL_SCHEDULER {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3315 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
3316 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3317 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3318 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3319 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3320 The individual schedulers can then implement this interface:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3321 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3322 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3323 cdl_option CYGSEM_KERNEL_SCHED_MLQUEUE {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3324 display "Multi-level queue scheduler"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3325 default_value 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3326 implements CYGINT_KERNEL_SCHEDULER
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3327 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3328 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3329
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3330 cdl_option CYGSEM_KERNEL_SCHED_BITMAP {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3331 display "Bitmap scheduler"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3332 default_value 0
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3333 implements CYGINT_KERNEL_SCHEDULER
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3334 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3335 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3336 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3337 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3338 Future schedulers can also implement this interface. The value of an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3339 interface, for the purposes of expression evaluation, is the number of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3340 active and enabled options which implement this interface. Packages
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3341 which rely on the presence of a scheduler can impose constraints such
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3342 as:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3343 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3344 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3345 requires CYGINT_KERNEL_SCHEDULER
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3346 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3347 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3348 If none of the schedulers are enabled, or if the kernel package is not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3349 loaded, then <varname>CYGINT_KERNEL_SCHEDULER</varname> will evaluate
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3350 to <literal>0</literal>. If at least one scheduler is active and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3351 enabled then the constraint will be satisfied.
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 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3354 Because interfaces have a calculated value determined by the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3355 implementors, the &default-value; and &calculated; properties are not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3356 applicable and should not appear in the body of a &cdl-interface;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3357 command. Interfaces have the <literal>data</literal> flavor by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3358 default, but the <literal>bool</literal> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3359 <literal>booldata</literal> flavors may be specified instead. A
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3360 <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
3361 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
3362 <literal>booldata</literal> interface is disabled if there are no
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3363 active and enabled implementors, otherwise it is enabled and has a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3364 value corresponding to the number of these implementors. Other
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3365 properties such as &requires; and &compile; can be used as normal.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3366 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3367 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3368 Some component writers will not want to use interfaces in this way.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3369 The reasoning is that their code will only have been tested with the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3370 existing schedulers, so the &requires; constraint needs to be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3371 expressed in terms of those schedulers; it is possible that the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3372 component will still work with a new scheduler, but there are no
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3373 guarantees. Other component writers may take a more optimistic view
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3374 and assume that their code will work with any scheduler until proven
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3375 otherwise. It is up to individual component writers to decide which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3376 approach is most appropriate in any given case.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3377 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3378 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3379 One common use for interfaces is to describe the hardware
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3380 functionality provided by a given target. For example the &CDL;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3381 scripts for a TCP/IP package might want to know whether or not the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3382 target hardware has an ethernet interface. Generally it is not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3383 necessary for the TCP/IP stack to know exactly which ethernet hardware
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3384 is present, since there should be a device driver which implements the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3385 appropriate functionality. In &CDL; terms the device drivers should
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3386 implement an interface <varname>CYGHWR_NET_DRIVERS</varname>, and the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3387 &CDL; scripts for the TCP/IP stack can use this in appropriate
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3388 expressions.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3389 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3390 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3391 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3392 Using the term <emphasis>interface</emphasis> for this concept is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3393 sometimes confusing, since the term has various other meanings as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3394 well. In practice, it is often correct. If there is a configuration
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3395 option that implements a given &CDL; interface, then usually this
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3396 option will enable some code that provides a particular interface at
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3397 the C or C++ level. For example an ethernet device driver implements
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3398 the &CDL; interface <varname>CYGHWR_NET_DRIVERS</varname>, and also
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3399 implements a set of C functions that can be used by the TCP/IP stack.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3400 Similarly <varname>CYGSEM_KERNEL_SCHED_MLQUEUE</varname> implements
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3401 the &CDL; interface <varname>CYGINT_KERNEL_SCHEDULER</varname> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3402 also provides the appropriate scheduling functions.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3403 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3404 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3405
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3406 </sect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3407
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3408 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3409 <!-- {{{ Package database -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3410
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3411 <sect1 id="language.database">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3412 <title>Updating the <database>ecos.db</database> database</title>
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 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3415 The current implementation of the component framework requires that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3416 all packages be present in a single component repository and listed in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3417 that repository's <database>ecos.db</database> database. This is not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3418 generally a problem for application developers who can consider the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3419 component repository a read-only resource, except when adding or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3420 removing packages via the administration tool. However it means that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3421 component writers need to do their development work inside a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3422 component repository as well, and update the database with details of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3423 their new package or packages. Future enhancements to the component
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3424 framework may allow new components to be developed outside a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3425 repository.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3426 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3427 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3428 Like most files related to the component framework, the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3429 <database>ecos.db</database> database is actually a &Tcl; script.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3430 Typical package entries would look like this:
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 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3433 package CYGPKG_LIBC {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3434 alias { "C library" libc clib clibrary }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3435 directory language/c/libc
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3436 script libc.cdl
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3437 description "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3438 This package enables compatibility with the ISO C standard - ISO/IEC
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3439 9899:1990. This allows the user application to use well known standard
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3440 C library functions, and in eCos starts a thread to invoke the user
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3441 function main()"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3442 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3443
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3444 package CYGPKG_IO_PCI {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3445 alias { "PCI configuration library" io_pci }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3446 directory io/pci
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3447 script io_pci.cdl
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3448 hardware
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3449 description "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3450 This package contains the PCI configuration library."
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3451 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3452 </programlisting>
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 The <literal>package</literal> command takes two arguments, a name and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3455 a body. The name must be the same as in the &cdl-package; command in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3456 the package's top-level &CDL; script. The body can contain the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3457 following five commands: <literal>alias</literal>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3458 <literal>directory</literal>, <literal>script</literal>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3459 <literal>hardware</literal> and <literal>description</literal>.
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
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3462 <variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3463 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3464 <term><literal>alias</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3465 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3466 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3467 Each package should have one or more aliases. The first alias is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3468 typically used when listing the known packages, because a string like
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3469 <literal>C&nbsp;library</literal> is a bit easier to read and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3470 understand than <varname>CYGPKG_LIBC</varname>. The other aliases are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3471 not used for output, but are accepted on input. For example the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3472 <application class="software">ecosconfig</application> command-line
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3473 tool will accept <literal>add&nbsp;libc</literal> as an option, as well
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3474 as <literal>add&nbsp;CYGPKG_LIBC</literal>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3475 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3476 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3477 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3478
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3479 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3480 <term><literal>directory</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3481 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3482 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3483 This is used to specify the location of the package relative to the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3484 root of the component repository. It should be noted that in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3485 current component framework this location cannot be changed in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3486 subsequent releases of the package: if for some reason it is desirable
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3487 to install a new release elsewhere in the repository, all the old
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3488 versions must first be uninstalled; the database cannot hold two
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3489 separate locations for one package.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3490 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3491 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3492 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3493
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3494 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3495 <term><literal>script</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3496 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3497 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3498 The <literal>script</literal> command specifies the location of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3499 package's top-level &CDL; script, in other words the one containing the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3500 &cdl-package; definition. If the package follows the <link
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3501 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
3502 this script will be in the <filename class="directory">cdl</filename>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3503 sub-directory, otherwise it will be relative to the package's top-level
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3504 directory. Again once a release has been made this file should not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3505 change in later releases. In practice the top-level script is generally
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3506 named after the package itself, so changing its name is unlikely to be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3507 useful.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3508 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3509 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3510 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3511
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3512 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3513 <term><literal>hardware</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3514 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3515 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3516 Packages which are tied to specific hardware, for example device
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3517 drivers and HAL packages, should indicate this in both the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3518 &cdl-package; command of the &CDL; script and in the database entry.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3519 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3520 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3521 </varlistentry>
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 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3524 <term><literal>description</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3525 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3526 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3527 This should give a brief description of the package. Typically the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3528 text for the &description; property in the &cdl-package; command will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3529 be re-used.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3530 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3531 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3532 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3533 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3534
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3535 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3536 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3537 Most of the information in the <database>ecos.db</database> file could
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3538 be obtained by a relatively simple utility. This would be passed a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3539 single argument identifying a package's top-level &CDL; script. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3540 directory path relative to the component repository root could be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3541 determined from the filename. The name, <literal>description</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3542 and <literal>hardware</literal> fields could be obtained from the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3543 script's &cdl-package; command. The &display; property would supply
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3544 the first alias, additional aliases could be obtained by extending the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3545 syntax of that property or by other means. Something along these lines
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3546 may be provided by a future release of the component framework.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3547 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3548 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3549 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3550 Currently the <database>ecos.db</database> database also holds
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3551 information about the various targets. When porting to a new target it
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3552 will be necessary to add information about the target to the database,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3553 as well as the details of the new platform HAL package and any related
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3554 packages.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3555 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3556
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3557 </sect1>
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 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3560
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3561 </chapter>