Mercurial > flash_v2

annotate host/libcdl/doc/language.sgml @ 1619:2aabaeffc161

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
* doc/redboot_epilogue.sgml: Comment out </part> to reflect change of 2004-04-19.
author jlarmour
date Thu, 29 Apr 2004 07:13:26 +0000
parents def85e4d96d2
children
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 <!-- =============================================================== -->
334
c9cbf5dfb306 Update documentation licenses to remove restriction on redistributing
bartv
parents: 210
diff changeset
13 <!-- Copyright (C) 2000, 2001, 2002 Red Hat, Inc. -->
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
14 <!-- -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
15 <!-- This material may be distributed only subject to the terms -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
16 <!-- and conditions set forth in the Open Publication License, v1.0 -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
17 <!-- or later (the latest version is presently available at -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
18 <!-- http://www.opencontent.org/openpub/) -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
19 <!-- Distribution of the work or derivative of the work in any -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
20 <!-- standard (paper) book form is prohibited unless prior -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
21 <!-- permission obtained from the copyright holder -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
22 <!-- =============================================================== -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
23 <!-- -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
24 <!-- ####COPYRIGHTEND#### -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
25 <!-- =============================================================== -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
26 <!-- #####DESCRIPTIONBEGIN#### -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
27 <!-- -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
28 <!-- Author(s): bartv -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
29 <!-- Contact(s): bartv -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
30 <!-- Date: 2000/02/06 -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
31 <!-- Version: 0.01 -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
32 <!-- -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
33 <!-- ####DESCRIPTIONEND#### -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
34 <!-- =============================================================== -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
35
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
36 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
37
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
38 <chapter id="language">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
39 <title>The CDL Language</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
40
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
41 <!-- {{{ Introit -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
42
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
43 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
44 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
45 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
46 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
47 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
48 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
49 &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
50 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
51 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
52 linkend="reference">.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
53 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
54
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
55 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
56 <!-- {{{ Language overview -->
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 <sect1 id="language.overview">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
59 <title>Language Overview</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
60 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
61 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
62 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
63 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
64 cdl_package CYGPKG_ERROR {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
65 display "Common error code support"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
66 compile strerror.cxx
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
67 include_dir cyg/error
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
68 description "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
69 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
70 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
71 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
72 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
73 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
74 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
75 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
76 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
77 convert error codes to textual representation."
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
78 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
79 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
80 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
81 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
82 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
83 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
84 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
85 <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
86 <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
87 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
88 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
89 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
90 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
91 &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
92 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
93 documentation.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
94 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
95 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
96 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
97 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
98 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
99 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
100 top-level of the <filename
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
101 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
102 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
103 &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
104 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
105 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
106 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
107 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
108 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
109 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
110 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
111 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
112 infrastructure package:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
113 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
114 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
115 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
116 display "Buffered tracing"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
117 default_value 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
118 active_if CYGDBG_USE_TRACING
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
119 description "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
120 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
121 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
122 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
123 &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
124 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
125 is enabled above."
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
126
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
127 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
128 display "Trace buffer size"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
129 flavor data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
130 default_value 32
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
131 legal_values 5 to 65535
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
132 description "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
133 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
134 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
135 wraps, stops recording, or generates output."
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
136 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
137
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
138 &hellip;
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 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
141 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
142 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
143 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
144 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
145 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
146 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
147 &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
148 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
149 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
150 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
151 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
152 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
153 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
154 &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
155 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
156 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
157 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
158 the configuration header files.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
159 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
160
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
161 </sect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
162
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 <!-- {{{ CDL commands -->
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 <sect1 id="language.commands">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
167 <title>CDL Commands</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
168 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
169 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
170 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
171 &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
172 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
173 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
174 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
175 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
176 cdl_package &lt;name&gt; {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
177 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
178 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
179
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
180 cdl_component &lt;name&gt; {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
181 &hellip;
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
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
184 cdl_option &lt;name&gt; {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
185 &hellip;
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
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
188 cdl_interface &lt;name&gt; {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
189 &hellip;
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 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
192 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
193 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
194 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
195 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
196 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
197 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
198 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
199 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
200 <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
201 make accidental name clashes very unlikely.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
202 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
203 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
204 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
205 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
206 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
207 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
208 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
209 <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
210 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
211 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
212 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
213 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
214 packages <link
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
215 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
216 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
217 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
218 <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
219 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
220 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
221 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
222 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
223 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
224 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
225 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
226 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
227 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
228 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
229 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
230 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
231 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
232 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
233 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
234 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
235 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
236 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
237 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
238 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
239 tool, facilitating navigation and modification.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
240 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
241 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
242 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
243 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
244 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
245 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
246 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
247 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
248 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
249 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
250 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
251 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
252 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
253 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
254 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
255 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
256 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
257 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
258 cdl_package CYGPKG_LIBC {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
259 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
260 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
261
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
262 cdl_component CYGPKG_LIBC_STRING {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
263 &hellip;
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
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
266 cdl_option CYGPKG_LIBC_CTYPE_INLINES {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
267 &hellip;
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 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
270 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
271 and:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
272 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
273 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
274 cdl_package CYGPKG_LIBC {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
275 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
276
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
277 cdl_component CYGPKG_LIBC_STRING {
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
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
281 cdl_option CYGPKG_LIBC_CTYPE_INLINES {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
282 &hellip;
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 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
285 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
286 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
287 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
288 &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
289 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
290 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
291 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
292 resulting behavior is still well-defined.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
293 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
294 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
295 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
296 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
297 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
298 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
299 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
300 cdl_component CYGPKG_LIBC_STDIO {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
301
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
302 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
303 &hellip;
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
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
306 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
307 &hellip;
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 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
310 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
311 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
312 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
313 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
314 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
315 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
316 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
317 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
318 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
319 <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
320 <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
321 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
322 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
323 cdl_package CYGPKG_LIBC {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
324 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
325
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
326 cdl_component CYGPKG_LIBC_STDIO {
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 script stdio.cdl
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
329 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
330 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
331 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
332 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
333 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
334 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
335 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
336 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
337 &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
338 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
339 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
340 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
341 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
342 properties for the current component.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
343 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
344 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
345 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
346 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
347 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
348 &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
349 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
350 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
351 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
352 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
353 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
354 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
355 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
356 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
357 components.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
358 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
359 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
360
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
361 </sect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
362
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 <!-- {{{ CDL properties -->
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 <!-- {{{ Introit -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
367
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
368 <sect1 id="language.properties">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
369 <title>CDL Properties</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
370 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
371 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
372 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
373 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
374 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
375 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
376 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
377 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
378 enabled or disabled by default.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
379 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
380 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
381 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
382 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
383 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
384 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
385 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
386 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
387 only rarely.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
388 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
389 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
390 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
391 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
392 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
393 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
394 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
395 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
396 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
397 &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
398 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
399 new kinds of arguments.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
400 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
401 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
402 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
403 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
404 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
405 <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
406 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
407 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
408 cdl_package CYGPKG_HAL_ARM {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
409 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
410 make -priority 1 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
411 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
412 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
413 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
414 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
415 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
416 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
417 <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
418 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
419 <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
420 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
421 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
422 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
423 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
424 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
425 legal_values -1 to 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
426 default_value -1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
427 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
428 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
429 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
430 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
431 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
432 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
433 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
434 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
435 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
436 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
437 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
438 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
439 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
440 legal_values -- -1 to 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
441 default_value -- -1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
442 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
443 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
444 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
445 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
446 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
447 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
448 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
449 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
450 dollar character <literal>$</literal>, square brackets
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
451 <literal>[</literal> and <literal>]</literal>, braces
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
452 <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
453 <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
454 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
455 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
456 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
457 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
458 see <xref linkend="language.tcl">.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
459 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
460 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
461 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
462 &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
463 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
464 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
465 &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
466 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
467 &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
468 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
469 &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
470 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
471 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
472 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
473 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
474 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
475 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
476 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
477 <xref linkend="build">.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
478 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
479
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
480 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
481 <!-- {{{ User-visible -->
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 <sect2 id="language.properties.user">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
484 <title>Information-providing Properties</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
485 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
486 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
487 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
488 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
489 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
490 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
491 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
492 <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
493 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
494 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
495 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
496 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
497 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
498 &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
499 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
500 user explicitly requests it.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
501 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
502 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
503 cdl_package CYGPKG_UITRON {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
504 display "uITRON compatibility layer"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
505 doc ref/ecos-ref.a.html
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
506 description "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
507 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
508 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
509 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
510 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
511 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
512 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
513 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
514 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
515 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
516 &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
517 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
518 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
519 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
520 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
521 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
522 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
523 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
524 </sect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
525
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
526 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
527 <!-- {{{ Hierarchy -->
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 <sect2 id="language.properties.hierarchy">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
530 <title>The Configuration Hierarchy</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
531 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
532 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
533 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
534 <link linkend="ref.script">&script;</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
535 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
536 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
537 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
538 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
539 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
540 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
541 <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
542 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
543 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
544 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
545 cdl_package CYGPKG_HAL_SH {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
546 display "SH architecture"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
547 parent CYGPKG_HAL
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
548 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
549 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
550 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
551 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
552 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
553 &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
554 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
555 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
556 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
557 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
558 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
559 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
560 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
561 &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
562 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
563 that may affect every package.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
564 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
565 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
566 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
567 &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
568 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
569 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
570 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
571 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
572 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
573 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
574 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
575 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
576 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
577 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
578 cdl_component CYGPKG_LIBC_STDIO {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
579 display "Standard input/output functions"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
580 flavor bool
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
581 requires CYGPKG_IO
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
582 requires CYGPKG_IO_SERIAL_HALDIAG
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
583 default_value 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
584 description "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
585 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
586
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
587 script stdio.cdl
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
588 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
589 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
590
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
591 </sect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
592
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 <!-- {{{ Value -->
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 <sect2 id="language.properties.value">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
597 <title>Value-related Properties</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
598 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
599 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
600 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
601 <link linkend="ref.calculated">&calculated;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
602 <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
603 <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
604 <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
605 <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
606 <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
607 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
608 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
609 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
610 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
611 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
612 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
613 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
614 kernel options, for example
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
615 <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
616 &requires; constraint on
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
617 <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
618 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
619 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
620 <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
621 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
622 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
623 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
624 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
625 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
626 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
627 <variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
628 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
629 <term><literal>flavor none</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
630 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
631 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
632 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
633 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
634 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
635 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
636 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
637 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
638 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
639 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
640 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
641 <term><literal>flavor bool</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
642 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
643 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
644 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
645 is fixed at <literal>1</literal>.
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 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
648 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
649 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
650 <term><literal>flavor data</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
651 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
652 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
653 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
654 is fixed at enabled.
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 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
657 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
658 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
659 <term><literal>flavor booldata</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
660 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
661 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
662 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
663 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
664 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
665 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
666 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
667 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
668 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
669 evaluation, and other consequences, see <xref
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
670 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
671 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
672 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
673 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
674 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
675 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
676 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
677 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
678 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
679 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
680 &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
681 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
682 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
683 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
684 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
685 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
686 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
687 argument, for example:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
688 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
689 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
690 # 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
691 # targets.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
692 cdl_option CYGNUM_HAL_RTC_PERIOD {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
693 display "Real-time clock period"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
694 flavor data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
695 calculated 12500
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
696 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
697 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
698 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
699 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
700 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
701 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
702 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
703 implementors.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
704 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
705 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
706 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
707 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
708 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
709 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
710 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
711 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
712 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
713 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
714 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
715 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
716 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
717 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
718 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
719 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
720 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
721 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
722 <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
723 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
724 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
725 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
726 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
727 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
728 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
729 display "Default Standard Time offset"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
730 flavor data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
731 legal_values -- -90000 to 90000
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
732 default_value -- 0
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
733 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
734 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
735 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
736 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
737 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
738 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
739 the configuration hierarchy: if the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
740 <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
741 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
742 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
743 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
744 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
745 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
746 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
747 <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
748 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
749 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
750 # 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
751 cdl_option CYGDBG_KERNEL_INSTRUMENT_BINSEM {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
752 active_if CYGPKG_KERNEL_SYNCH
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
753 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
754 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
755 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
756 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
757 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
758 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
759 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
760 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
761 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
762 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
763 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
764 display "Cirrus Logic ethernet driver"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
765 implements CYGHWR_NET_DRIVERS
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
766 implements CYGHWR_NET_DRIVER_ETH0
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
767 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
768 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
769 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
770 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
771 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
772 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
773 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
774 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
775 not being used at all.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
776 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
777 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
778 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
779 display "Per-thread errno"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
780 doc ref/ecos-ref.15.html
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
781 requires CYGVAR_KERNEL_THREADS_DATA
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
782 default_value 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
783 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
784 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
785 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
786 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
787 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
788 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
789 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
790
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
791 </sect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
792
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 <!-- {{{ Header file generation -->
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 <sect2 id="language.properties.define">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
797 <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
798 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
799 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
800 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
801 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
802 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
803 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
804 <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
805 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
806 include:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
807 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
808 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
809 #define CYGFUN_LIBC_TIME_POSIX 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
810 #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
811 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
812 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
813 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
814 generation process:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
815 <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
816 <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
817 <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
818 <link linkend="ref.define">&define;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
819 <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
820 <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
821 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
822 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
823 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
824 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
825 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
826 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
827 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
828 <varname>CYGPKG_KERNEL</varname> is <filename
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
829 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
830 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
831 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
832 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
833 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
834 package is <filename
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
835 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
836 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
837 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
838 cdl_package CYGPKG_HAL_SPARCLITE {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
839 display "SPARClite architecture"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
840 parent CYGPKG_HAL
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
841 hardware
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
842 define_header hal_sparclite.h
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
843 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
844 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
845 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
846 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
847 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
848 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
849 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
850 pages</link> for more details.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
851 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
852 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
853 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
854 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
855 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
856 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
857 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
858 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
859 &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
860 arguments.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
861 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
862 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
863 cdl_component CYG_HAL_STARTUP {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
864 display "Startup type"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
865 flavor data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
866 legal_values { "RAM" "ROM" }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
867 default_value {"RAM"}
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
868 no_define
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
869 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
870 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
871 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
872 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
873 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
874 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
875 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
876 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
877 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
878 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
879 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
880 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
881 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
882 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
883 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
884 generate a four-digit hexadecimal number.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
885 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
886 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
887 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
888 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
889 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
890 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
891 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
892 information.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
893 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
894 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
895 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
896 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
897 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
898 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
899 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
900 actions that might be appropriate.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
901 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
902
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
903 </sect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
904
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 <!-- {{{ Builds -->
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 <sect2 id="language.properties.build">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
909 <title>Controlling what gets Built</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
910 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
911 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
912 <link linkend="ref.compile">&compile;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
913 <link linkend="ref.make">&make;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
914 <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
915 <link linkend="ref.library">&library;</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
916 <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
917 <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
918 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
919 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
920 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
921 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
922 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
923 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
924 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
925 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
926 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
927 <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
928 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
929 files:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
930 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
931 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
932 cdl_package CYGPKG_ERROR {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
933 display "Common error code support"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
934 compile strerror.cxx
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
935 include_dir cyg/error
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
936 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
937 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
938 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
939 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
940 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
941 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
942 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
943 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
944 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
945 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
946 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
947 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
948 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
949 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
950 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
951 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
952 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
953 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
954 &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
955 example:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
956 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
957 <programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
958 cdl_package CYGPKG_HAL_MN10300_AM33 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
959 display "MN10300 AM33 variant"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
960 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
961 make {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
962 &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
963 $(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
964 $(CFLAGS) -o $@ $&lt;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
965 @echo $@ ": \\" &gt; $(notdir $@).deps
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
966 @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
967 @echo &gt;&gt; $(notdir $@).deps
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
968 @rm target.tmp
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
969 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
970 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
971 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
972 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
973 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
974 generally, see <xref linkend="build">.
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 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
977 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
978 <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
979 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
980 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
981 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
982 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
983 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
984 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
985 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
986 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
987 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
988 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
989 library, since headers like <filename
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
990 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
991 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
992 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
993 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
994 header files, for example:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
995 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
996 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
997 cdl_package CYGPKG_INFRA {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
998 display "Infrastructure"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
999 include_dir cyg/infra
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1000 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1001 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1002 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1003 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1004 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
1005 <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
1006 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
1007 <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
1008 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
1009 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1010 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1011 For packages which follow the <link
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1012 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
1013 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
1014 <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
1015 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
1016 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
1017 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
1018 explicitly in an &include-files; property.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1019 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1020
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1021 </sect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1022
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 <!-- {{{ Miscellaneous -->
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 <sect2 id="language.properties.miscellaneous">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1027 <title>Miscellaneous Properties</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1028 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1029 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
1030 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
1031 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
1032 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
1033 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
1034 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
1035 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
1036 does not take any arguments.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1037 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1038 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1039 cdl_package CYGPKG_HAL_MIPS {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1040 display "MIPS architecture"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1041 parent CYGPKG_HAL
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1042 hardware
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1043 include_dir cyg/hal
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1044 define_header hal_mips.h
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1045 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1046 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1047 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1048 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1049 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
1050 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
1051 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1052 </sect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1053
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1054 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1055
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1056 </sect1>
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 <!-- {{{ Naming conventions -->
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 <sect1 id="language.naming">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1062 <title>Option Naming Convention</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1063 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1064 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
1065 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
1066 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
1067 &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
1068 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
1069 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
1070 other packages.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1071 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1072 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1073 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
1074 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
1075 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
1076 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
1077 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
1078 &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
1079 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
1080 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
1081 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
1082 <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
1083 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
1084 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
1085 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
1086 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
1087 wish to follow this convention.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1088 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1089 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1090 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
1091 <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
1092 several different parts:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1093 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1094 <orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1095 <listitem>
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 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
1098 <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
1099 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
1100 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
1101 <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
1102 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
1103 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
1104 organization.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1105 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1106 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1107 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
1108 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
1109 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
1110 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
1111 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
1112 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
1113 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
1114 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
1115 to be acceptable.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1116 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1117 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1118 <listitem>
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 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
1121 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
1122 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
1123 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1124 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1125 <listitem>
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 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
1128 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
1129 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
1130 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
1131 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
1132 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1133 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1134 <listitem>
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 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
1137 itself.
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 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1140 </orderedlist>
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 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
1143 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
1144 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
1145 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
1146 <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
1147 <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
1148 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
1149 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
1150 interpret the following guidelines:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1151 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1152 <variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1153 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1154 <term><literal>xxxARC_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1155 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1156 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
1157 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
1158 in architectural or variant HAL packages.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1159 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1160 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1161 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1162 <term><literal>xxxHWR_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1163 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1164 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
1165 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
1166 platform HAL packages.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1167 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1168 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1169 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1170 <term><literal>xxxPKG_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1171 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1172 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
1173 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
1174 <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
1175 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
1176 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
1177 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1178 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1179 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1180 <term><literal>xxxGLO_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1181 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1182 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
1183 preferences.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1184 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1185 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1186 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1187 <term><literal>xxxDBG_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1188 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1189 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
1190 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
1191 some part of the system.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1192 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1193 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1194 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1195 <term><literal>xxxTST_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1196 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1197 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
1198 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
1199 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
1200 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1201 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1202 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1203 <term><literal>xxxFUN_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1204 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1205 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
1206 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
1207 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
1208 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
1209 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
1210 interface-related tags is applicable.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1211 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1212 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1213 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1214 <term><literal>xxxVAR_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1215 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1216 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
1217 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
1218 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1219 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1220 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1221 <term><literal>xxxCLS_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1222 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1223 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
1224 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
1225 absence of an entire class.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1226 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1227 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1228 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1229 <term><literal>xxxMFN_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1230 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1231 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
1232 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
1233 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1234 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1235 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1236 <term><literal>xxxSEM_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1237 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1238 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
1239 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
1240 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
1241 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
1242 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
1243 <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
1244 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
1245 the system's behavior.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1246 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1247 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1248 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1249 <term><literal>xxxIMP_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1250 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1251 <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
1252 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
1253 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
1254 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
1255 set of functions should get inlined.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1256 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1257 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1258 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1259 <term><literal>xxxNUM_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1260 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1261 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
1262 scheduling priority levels.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1263 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1264 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1265 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1266 <term><literal>xxxDAT_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1267 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1268 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
1269 device name.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1270 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1271 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1272 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1273 <term><literal>xxxBLD_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1274 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1275 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
1276 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
1277 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1278 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1279 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1280 <term><literal>xxxINT_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1281 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1282 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
1283 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
1284 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
1285 see <xref linkend="language.interface">.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1286 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1287 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1288 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1289 <term><literal>xxxPRI_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1290 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1291 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
1292 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
1293 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
1294 &define-proc; property.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1295 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1296 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1297 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1298 <term><literal>xxxSRC_</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1299 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1300 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
1301 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
1302 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
1303 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1304 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1305 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1306
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1307 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1308 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
1309 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
1310 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
1311 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
1312 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
1313 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
1314 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
1315 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
1316 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
1317 <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
1318 configuration contained some other package
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1319 <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
1320 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
1321 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
1322 <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
1323 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
1324 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
1325 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
1326 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
1327 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
1328 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1329
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1330 </sect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1331
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 <!-- {{{ Introduction to Tcl -->
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 <sect1 id="language.tcl">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1336 <title>An Introduction to Tcl</title>
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 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1339 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
1340 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
1341 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
1342 <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
1343 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
1344 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
1345 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
1346 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
1347 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
1348 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1349
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1350 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1351 cdl_option CYGDAT_UITRON_MEMPOOLFIXED_EXTERNS {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1352 display "Externs for initialization"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1353 flavor data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1354 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
1355 fpool2[ 2000 ], \\\n\
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1356 fpool3[ 2000 ];"}
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1357 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1358 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1359 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1360
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1361 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1362 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
1363 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
1364 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
1365 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
1366 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
1367 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
1368 prevents command substitution for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1369 <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
1370 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
1371 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
1372 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1373
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1374 <screen width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1375 "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
1376 </screen>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1377
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1378 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1379 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
1380 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
1381 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
1382 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
1383 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1384 <screen width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1385 static char fpool1[ 2000 ], \
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1386 fpool2[ 2000 ], \
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1387 fpool3[ 2000 ];
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1388 </screen>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1389
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1390 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1391 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
1392 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
1393 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1394 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1395 #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
1396 fpool2[ 2000 ], \
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1397 fpool3[ 2000 ];
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1398 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1399
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1400 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1401 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
1402 &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
1403 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
1404 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
1405 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
1406 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
1407 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
1408 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
1409 language as well as the syntax.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1410 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1411 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1412 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
1413 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
1414 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
1415 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
1416 languages, which can confuse newcomers.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1417 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1418 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1419 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
1420 <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
1421 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
1422 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
1423 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
1424 following example:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1425 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1426 <screen width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1427 puts Hello
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1428 set x 42
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1429 </screen>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1430 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1431 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
1432 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
1433 <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
1434 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
1435 <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
1436 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
1437 instead:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1438 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1439 <screen width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1440 puts Hello;set x 42
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1441 </screen>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1442 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1443 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
1444 does not serve to separate arguments.
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 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1447 Now consider the following:
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 <screen width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1450 set x Hello world
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1451 </screen>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1452 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1453 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
1454 <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
1455 <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
1456 <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
1457 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
1458 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
1459 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1460 <screen width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1461 set x "Hello world"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1462 </screen>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1463 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1464 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
1465 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
1466 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
1467 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
1468 <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
1469 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
1470 of &CDL; scripts. For example:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1471 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1472 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1473 cdl_option CYG_HAL_STARTUP {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1474 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1475 default_value "RAM"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1476 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1477 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1478 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1479 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
1480 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
1481 <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
1482 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
1483 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
1484 <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
1485 currently loaded. Therefore the option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1486 <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
1487 <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
1488 avoid this, for example
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1489 <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
1490 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1491 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1492 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1493 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
1494 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
1495 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
1496 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1497 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1498 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1499 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
1500 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
1501 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
1502 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
1503 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1504 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1505 cdl_package CYGPKG_ERROR {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1506 description "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1507 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
1508 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
1509 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
1510 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
1511 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
1512 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
1513 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
1514 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
1515 convert error codes to textual representation."
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1516 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1517 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1518 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1519 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1520 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
1521 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
1522 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
1523 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
1524 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
1525 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
1526 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
1527 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
1528 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1529 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1530 puts "Hello\nworld\n"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1531 puts \
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1532 "Hello
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1533 world
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1534 "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1535 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1536 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1537 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
1538 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
1539 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
1540 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
1541 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
1542 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1543 <screen width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1544 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
1545 </screen>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1546 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1547 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
1548 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
1549 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
1550 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
1551 <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
1552 <footnote>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1553 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1554 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
1555 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
1556 <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
1557 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
1558 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
1559 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1560 </footnote>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1561 and then the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1562 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
1563 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
1564 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
1565 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
1566 will not be treated specially.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1567 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1568 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1569 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
1570 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
1571 &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
1572 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
1573 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
1574 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
1575 require backslash-escapes.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1576 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1577 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1578 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
1579 variable substitution:
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 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1582 set x [expr 6 * 9]
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1583 puts "The answer is $x"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1584 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1585 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1586 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
1587 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
1588 &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
1589 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
1590 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1591 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1592 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
1593 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
1594 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
1595 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
1596 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
1597 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1598 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1599 default_value {"RAM"}
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1600 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1601 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1602 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
1603 <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
1604 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
1605 one of the following:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1606 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1607 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1608 default_value \"RAM\"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1609 default_value "\"RAM\""
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1610 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1611 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1612 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
1613 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
1614 braces:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1615 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1616 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1617 cdl_option &lt;name&gt; {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1618 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1619 };
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1620 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1621 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1622 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
1623 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
1624 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
1625 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
1626 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
1627 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
1628 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1629 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1630 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
1631 <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
1632 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
1633 following:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1634 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1635 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1636 # This is a comment
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1637 puts "Hello" # world
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1638 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1639 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1640 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
1641 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
1642 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
1643 <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
1644 <literal>Hello</literal>, <literal>#</literal> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1645 <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
1646 <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
1647 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
1648 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1649 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1650 puts "Hello"; # world
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1651 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1652 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1653 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
1654 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
1655 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
1656 comment.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1657 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1658 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1659 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
1660 following:
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 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1663 cdl_option WHATEVER {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1664 # This is a comment }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1665 default_value 0
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1666 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1667 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1668 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1669 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1670 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
1671 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
1672 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
1673 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
1674 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
1675 to <literal>cdl_option</literal> is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1676 <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
1677 </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
1678 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
1679 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
1680 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
1681 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
1682 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
1683 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
1684 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1685 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1686 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
1687 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
1688 resources are available. A reasonable starting point is the
491
def85e4d96d2 http://dev.scriptics.com/ is now http://www.tcl.tk/
jlarmour
parents: 334
diff changeset
1689 <ulink url="http://www.tcl.tk/scripting/">Scriptics developer
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1690 web site</ulink>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1691 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1692 </sect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1693
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1694 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1695 <!-- {{{ Values and Expressions -->
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 <sect1 id="language.values">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1698 <title>Values and Expressions</title>
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 <!-- {{{ Introit -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1701
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1702 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1703 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
1704 configuration option such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1705 <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
1706 <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
1707 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
1708 <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
1709 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
1710 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
1711 <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
1712 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
1713 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1714 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1715 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
1716 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
1717 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
1718 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
1719 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
1720 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
1721 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
1722 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
1723 <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
1724 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1725 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1726 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
1727 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1728
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1729 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1730 <!-- {{{ Option Values -->
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 <sect2 id="language.values.value">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1733 <!-- {{{ Introit -->
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 <title>Option Values</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1736
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1737 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1738 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
1739 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1740 <orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1741 <listitem>
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 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
1744 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1745 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1746 <listitem>
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 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
1749 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1750 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1751 <listitem>
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 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
1754 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1755 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1756 <listitem>
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 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
1759 associated data which constitutes its value.
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 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1762 </orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1763
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1764 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1765 <!-- {{{ Loaded -->
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 <sect3 id="language.values.value.loaded">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1768 <title>Is the Option Loaded?</title>
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 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1771 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
1772 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
1773 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
1774 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
1775 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
1776 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
1777 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
1778 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
1779 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
1780 define the resulting behavior.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1781 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1782 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1783 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
1784 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
1785 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
1786 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
1787 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
1788 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
1789 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
1790 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
1791 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
1792 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
1793 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
1794 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
1795 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
1796 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1797 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1798 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
1799 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
1800 contain the following constraints:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1801 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1802 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1803 requires CYGPKG_KERNEL
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1804 requires CYGPKG_KERNEL_THREADS_DATA
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1805 requires !CYGSEM_KERNEL_SCHED_TIMESLICE
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1806 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1807 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1808 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
1809 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
1810 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
1811 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
1812 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1813 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1814 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
1815 follows:
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 <orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1818 <listitem>
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 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
1821 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
1822 be satisfied but
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1823 <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
1824 be satisfied.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1825 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1826 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1827 <listitem>
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 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
1830 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
1831 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
1832 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
1833 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
1834 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
1835 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
1836 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1837 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1838 <listitem>
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 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
1841 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
1842 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
1843 &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
1844 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1845 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1846 </orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1847
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1848 </sect3>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1849
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 <!-- {{{ Active -->
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 <sect3 id="language.values.value.active">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1854 <title>Is the Option Active</title>
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 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1857 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
1858 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
1859 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
1860 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
1861 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
1862 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
1863 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
1864 the buffer sizes.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1865 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1866 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1867 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
1868 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
1869 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
1870 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
1871 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
1872 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
1873 may be grayed out.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1874 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1875 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1876 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
1877 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
1878 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
1879 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
1880 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
1881 inactive:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1882 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1883 <orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1884 <listitem>
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 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
1887 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
1888 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
1889 <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
1890 <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
1891 as well.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1892 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1893 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1894 <listitem>
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 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
1897 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
1898 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
1899 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
1900 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1901 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1902 <listitem>
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 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
1905 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
1906 of the form
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1907 <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
1908 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
1909 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1910 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1911 <listitem>
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 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
1914 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
1915 similar properties will be ignored.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1916 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1917 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1918 <listitem>
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 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
1921 of the configuration. For example
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1922 <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
1923 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
1924 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
1925 (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
1926 dependency on <varname>CYGPKG_LIBM</varname>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1927 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1928 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1929 </orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1930 </sect3>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1931
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1932 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1933 <!-- {{{ Enabled/data -->
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 <sect3 id="language.values.value.enabled">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1936 <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
1937
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1938 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1939 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
1940 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
1941 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
1942 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
1943 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
1944 <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
1945 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
1946 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
1947 consequences.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1948 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1949 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1950 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
1951 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
1952 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
1953 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
1954 &flavor; property:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1955 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1956 <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
1957 <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
1958 <thead>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1959 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1960 <entry>Flavor</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1961 <entry>Enabled</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1962 <entry>Data</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1963 </row
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1964 </thead>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1965 <tbody>
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 <entry><literal>none</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1968 <entry>Always enabled</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1969 <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
1970 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1971 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1972 <entry><literal>bool</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1973 <entry>User-modifiable</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1974 <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
1975 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1976 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1977 <entry><literal>data</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1978 <entry>Always enabled</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1979 <entry>User-modifiable</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1980 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1981 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1982 <entry><literal>booldata</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1983 <entry>User-modifiable</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1984 <entry>User-modifiable</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1985 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1986 </tbody>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1987 </tgroup>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1988 </informaltable>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1989 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1990 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
1991 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1992 <orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
1993 <listitem>
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 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
1996 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
1997 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
1998 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
1999 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
2000 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
2001 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2002 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2003 <listitem>
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 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
2006 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
2007 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
2008 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
2009 generally has the expected result.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2010 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2011 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2012 <listitem>
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 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
2015 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
2016 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
2017 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2018 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2019 <listitem>
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 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
2022 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
2023 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
2024 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
2025 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
2026 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
2027 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
2028 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
2029 <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
2030 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
2031 active).
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2032 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2033 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2034 <listitem>
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 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
2037 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
2038 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
2039 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
2040 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
2041 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
2042 &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
2043 system.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2044 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2045 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2046 </orderedlist>
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 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
2049 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
2050 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
2051 <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
2052 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
2053 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
2054 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
2055 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2056
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2057 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2058 <title>&CDL; Flavors</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2059 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2060 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
2061 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
2062 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
2063 works the way it does.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2064 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2065 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2066 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
2067 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
2068 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
2069 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
2070 arguments are as follows:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2071 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2072 <orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2073 <listitem>
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 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
2076 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
2077 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
2078 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
2079 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
2080 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2081 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2082 <listitem>
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 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
2085 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
2086 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
2087 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
2088 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
2089 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
2090 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
2091 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
2092 number, for example
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2093 <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
2094 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2095 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2096 <listitem>
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 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
2099 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
2100 &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
2101 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2102 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2103 </orderedlist>
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 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
2106 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
2107 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
2108 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
2109 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2110 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2111 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
2112 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
2113 should be possible to describe
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2114 <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
2115 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
2116 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
2117 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2118 <orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2119 <listitem>
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 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
2122 &CDL; option. A constraint such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2123 <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
2124 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
2125 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
2126 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
2127 &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
2128 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
2129 <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
2130 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
2131 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
2132 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2133 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2134 <listitem>
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 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
2137 <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
2138 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
2139 <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
2140 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
2141 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
2142 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2143 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2144 <listitem>
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 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
2147 example the default value of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2148 <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
2149 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2150 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2151 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
2152 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
2153 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
2154 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
2155 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2156 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2157 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
2158 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
2159 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
2160 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2161 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2162 <listitem>
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 &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
2165 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
2166 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
2167 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
2168 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
2169 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2170 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2171 </orderedlist>
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 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
2174 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
2175 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
2176 language that underlies &CDL;.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2177 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2178 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2179
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2180 </sect3>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2181
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 <!-- {{{ Examples -->
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 <sect3 id="language.values.value.examples">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2186 <title>Some Examples</title>
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 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2189 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
2190 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
2191 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2192 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2193 cdl_component CYGPKG_LIBC_RAND {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2194 flavor none
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2195 compile stdlib/rand.cxx
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2196
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2197 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
2198 requires CYGVAR_KERNEL_THREADS_DATA
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2199 default_value 0
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2200 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2201
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2202 cdl_option CYGNUM_LIBC_RAND_SEED {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2203 flavor data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2204 legal_values 0 to 0x7fffffff
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2205 default_value 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2206 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2207
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2208 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
2209 flavor data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2210 legal_values 0 to 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2211 default_value 0
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2212 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2213 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2214 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2215 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2216 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
2217 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
2218 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
2219 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
2220 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
2221 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
2222 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
2223 <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
2224 <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
2225 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
2226 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
2227 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
2228 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
2229 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2230 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2231 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
2232 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
2233 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
2234 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
2235 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
2236 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
2237 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
2238 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2239 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2240 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
2241 <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
2242 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
2243 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
2244 active as well.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2245 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2246 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2247 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
2248 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
2249 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
2250 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
2251 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
2252 <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
2253 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
2254 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
2255 <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
2256 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
2257 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2258 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2259 #define CYGPKG_LIBC_RAND 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2260 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2261 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2262 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
2263 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
2264 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
2265 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
2266 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
2267 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
2268 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
2269 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
2270 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
2271 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
2272 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
2273 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
2274 might be more appropriate.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2275 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2276 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2277 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
2278 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
2279 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
2280 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
2281 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
2282 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
2283 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
2284 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
2285 <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
2286 &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
2287 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
2288 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
2289 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2290 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2291 #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
2292 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2293 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2294 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
2295 &requires; constraint on
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2296 <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
2297 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
2298 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
2299 include the kernel package then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2300 <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
2301 <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
2302 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
2303 satisfied.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2304 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2305 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2306 <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
2307 <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
2308 <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
2309 component framework will generate appropriate
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2310 <literal>#define's</literal>:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2311 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2312 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2313 #define CYGNUM_LIBC_RAND_SEED 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2314 #define CYGNUM_LIBC_RAND_SEED_1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2315 #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
2316 #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
2317 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2318 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2319 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
2320 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
2321 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
2322 constraint of the form
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2323 <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
2324 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
2325 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
2326 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
2327 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
2328 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
2329 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
2330 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
2331 options are active and enabled.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2332 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2333 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2334 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2335 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
2336 <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
2337 <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
2338 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
2339 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
2340 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
2341 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2342 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2343
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2344 </sect3>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2345
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 </sect2>
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 <!-- {{{ Expressions -->
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 <sect2 id="language.expression">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2353 <title>Ordinary Expressions</title>
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 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2356 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
2357 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2358 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2359 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
2360 default_value { (CYG_HAL_STARTUP == "RAM" &&
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2361 !CYGDBG_HAL_DEBUG_GDB_INCLUDE_STUBS &&
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2362 !CYGINT_HAL_USE_ROM_MONITOR_UNSUPPORTED &&
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2363 !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
2364 default_value { "\"/dev/ser0\"" }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2365 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2366 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2367 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
2368 &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
2369 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
2370 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
2371 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
2372 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
2373 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2374 <orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2375 <listitem>
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 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
2378 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
2379 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
2380 <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
2381 <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
2382 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
2383 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2384 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2385 <listitem>
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 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
2388 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
2389 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
2390 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
2391 processing on the subsequent arguments.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2392 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2393 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2394 <listitem>
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 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
2397 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
2398 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
2399 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2400 <programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2401 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
2402 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
2403 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2404 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2405 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2406 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2407 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
2408 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2409 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2410 </orderedlist>
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 &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
2413 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
2414 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
2415 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
2416 <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
2417 <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
2418 <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
2419 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
2420 <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
2421 <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
2422 <literal>&gt;=</literal>; the bitwise operators
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2423 <literal>&amp;</literal>, <literal>^</literal> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2424 <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
2425 <literal>||</literal>; the string concatenation operator
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2426 <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
2427 <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
2428 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
2429 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
2430 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
2431 precedence:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2432 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2433 <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
2434 <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
2435 <colspec colnum=1 align="center">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2436 <colspec colnum=2 align="center">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2437 <colspec colnum=3 align="center">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2438 <thead>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2439 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2440 <entry>Priority</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2441 <entry>Operators</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2442 <entry>Category</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2443 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2444 </thead>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2445 <tbody>
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 <entry>16</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2448 <entry>references, constants</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2449 <entry>basic elements</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2450 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2451 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2452 <entry>15</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2453 <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
2454 <entry>function calls</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2455 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2456 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2457 <entry>14</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2458 <entry><literal>~</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2459 <entry>bitwise not</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2460 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2461 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2462 <entry>14</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2463 <entry><literal>!</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2464 <entry>logical not</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2465 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2466 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2467 <entry>14</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2468 <entry><literal>-</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2469 <entry>arithmetic negation</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2470 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2471 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2472 <entry>13</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2473 <entry><literal>* / %</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2474 <entry>multiplicative arithmetic</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2475 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2476 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2477 <entry>12</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2478 <entry><literal>+ - .</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2479 <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
2480 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2481 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2482 <entry>11</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2483 <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
2484 <entry>bitwise shifts</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2485 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2486 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2487 <entry>10</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2488 <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
2489 <entry>inequality</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2490 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2491 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2492 <entry>9</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2493 <entry><literal>== !=</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2494 <entry>comparison</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2495 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2496 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2497 <entry>8</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2498 <entry><literal>&</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2499 <entry>bitwise and</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2500 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2501 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2502 <entry>7</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2503 <entry><literal>^</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2504 <entry>bitwise xor</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2505 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2506 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2507 <entry>6</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2508 <entry><literal>|</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2509 <entry>bitwise or</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2510 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2511 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2512 <entry>5</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2513 <entry><literal>&&</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2514 <entry>logical and</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2515 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2516 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2517 <entry>4</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2518 <entry><literal>||</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2519 <entry>logical or</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2520 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2521 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2522 <entry>3</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2523 <entry><literal>xor, eqv</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2524 <entry>logical equivalance</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2525 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2526 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2527 <entry>2</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2528 <entry><literal>implies</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2529 <entry>logical implication</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2530 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2531 <row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2532 <entry>1</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2533 <entry><literal>? :</literal></entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2534 <entry>conditional</entry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2535 </row>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2536 </tbody>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2537 </tgroup>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2538 </informaltable>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2539
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2540 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2541 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
2542 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
2543 example:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2544 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2545 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2546 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
2547 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2548 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2549 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
2550 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
2551 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
2552 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
2553 linkend="language.functions">.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2554 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2555 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2556 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
2557 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
2558 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
2559 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
2560 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
2561 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
2562 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
2563 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
2564 example use would be:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2565 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2566 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2567 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
2568 (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
2569 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2570 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2571 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
2572 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
2573 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
2574 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2575 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2576 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
2577 <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
2578 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
2579 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
2580 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
2581 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
2582 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
2583 linkend="language.values.value">.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2584 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2585 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2586 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
2587 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
2588 &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
2589 Consider the following:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2590 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2591 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2592 default_value "RAM"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2593 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2594 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2595 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
2596 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
2597 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
2598 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
2599 <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
2600 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
2601 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2602 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2603 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
2604 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
2605 again necessary, for example:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2606 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2607 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2608 default_value { "\"/dev/ser0\"" }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2609 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2610 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2611 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
2612 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
2613 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
2614 <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
2615 <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
2616 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
2617 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
2618 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
2619 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
2620 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2621 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2622 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
2623 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
2624 following two lines are equivalent:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2625 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2626 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2627 requires CYGNUM_UITRON_SEMAS > 10
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2628 requires { CYGNUM_UITRON_SEMAS > "10" }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2629 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2630 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2631 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
2632 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
2633 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
2634 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
2635 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
2636 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
2637 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
2638 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
2639 <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
2640 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
2641 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2642 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2643 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
2644 <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
2645 &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
2646 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
2647 identifier instead of as a string.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2648 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2649 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2650 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
2651 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
2652 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
2653 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
2654 they are necessary. For example, given
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2655 <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
2656 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
2657 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
2658 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
2659 gets evaluated. Given
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2660 <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
2661 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
2662 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
2663 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
2664 language.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2665 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2666 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2667 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
2668 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
2669 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
2670 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
2671 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2672 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2673 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
2674 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
2675 <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
2676 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
2677 <literal>^</literal>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2678 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2679 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2680 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
2681 double precision arithmetic: unary <literal>-</literal>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2682 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
2683 <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
2684 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
2685 <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
2686 <literal>&gt;=</literal>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2687 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2688 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2689 The equality <literal>==</literal> and inequality
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2690 <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
2691 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
2692 (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
2693 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
2694 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2695 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2696 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
2697 <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
2698 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
2699 <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
2700 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
2701 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
2702 <literal>1</literal>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2703 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2704 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2705 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
2706 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
2707 the second or third operands.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2708 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2709 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2710 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
2711 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
2712 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
2713 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2714
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2715 <note>
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 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
2718 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
2719 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
2720 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2721 <orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2722 <listitem>
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 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
2725 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
2726 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
2727 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
2728 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
2729 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
2730 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
2731 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
2732 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
2733 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2734 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2735 <listitem>
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 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
2738 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
2739 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2740 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2741 <listitem>
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 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
2744 <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
2745 <literal>!A&nbsp;||B</literal>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2746 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2747 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2748 <listitem>
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 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
2751 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
2752 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
2753 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
2754 indirection operator.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2755 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2756 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2757 <listitem>
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 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
2760 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
2761 &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
2762 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
2763 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
2764 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
2765 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
2766 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
2767 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
2768 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
2769 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
2770 performance.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2771 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2772 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2773 </orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2774 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2775
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2776 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2777 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2778 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
2779 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
2780 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
2781 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
2782 package will be used instead.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2783 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2784 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2785
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2786 </sect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2787
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 <!-- {{{ Functions -->
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 <sect2 id="language.functions">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2792 <title>Functions</title>
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 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2795 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
2796 using the usual syntax, for example;
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 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2799 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
2800 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2801 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2802 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
2803 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2804
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2805 <variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2806
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2807 <!-- {{{ get_data() -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2808
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2809 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2810 <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
2811 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2812 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2813 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
2814 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
2815 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
2816 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
2817 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
2818 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
2819 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
2820 <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
2821 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
2822 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2823 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2824 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2825
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2826 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2827 <!-- {{{ is_active() -->
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 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2830 <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
2831 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2832 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2833 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
2834 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
2835 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
2836 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
2837 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
2838 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
2839 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
2840 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2841 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2842 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
2843 (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
2844 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2845 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2846 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
2847 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
2848 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
2849 be at least 16K.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2850 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2851 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2852 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
2853 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
2854 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
2855 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
2856 terms in the associated expressions.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2857 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2858 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2859 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2860
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2861 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2862 <!-- {{{ is_enabled() -->
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 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2865 <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
2866 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2867 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2868 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
2869 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
2870 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
2871 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
2872 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
2873 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
2874 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
2875 <function>is_active</function> and possibly
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2876 <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
2877 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
2878 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2879 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2880 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2881
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2882 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2883 <!-- {{{ is_loaded() -->
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 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2886 <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
2887 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2888 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2889 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
2890 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
2891 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
2892 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
2893 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
2894 constraints are usually equivalent:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2895 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2896 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2897 requires { CYGPKG_KERNEL }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2898 requires { is_loaded(CYGPKG_KERNEL) }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2899 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2900 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2901 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
2902 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
2903 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
2904 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
2905 <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
2906 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
2907 are evaluated.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2908 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2909 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2910 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
2911 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
2912 constraints.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2913 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2914 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2915 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2916
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2917 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2918 <!-- {{{ is_substr() -->
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 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2921 <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
2922 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2923 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2924 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
2925 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
2926 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
2927 arbitrary expressions, and returns a boolean.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2928 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2929 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2930 <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
2931 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
2932 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
2933 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
2934 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
2935 the following conditions are satisfied:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2936 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2937 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2938 is_substr("abracadabra", "abra")
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2939 is_substr("abracadabra", " abra")
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2940 is_substr("hocus pocus", " pocus")
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 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2943 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2944 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
2945 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
2946 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
2947 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
2948 following condition is not satisfied.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2949 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2950 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2951 is_substr("abracadabra", " abra ")
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2952 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2953 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2954 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
2955 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
2956 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
2957 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2958 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2959 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
2960 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
2961 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
2962 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
2963 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
2964 from the current value.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2965 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2966 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2967 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
2968 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
2969 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2970 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2971 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
2972 example, given an initial value of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2973 <<varname>CYGBLD_GLOBAL_CFLAGS</varname> of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2974 <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
2975 <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
2976 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2977 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2978 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
2979 <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
2980 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2981 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2982 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2983
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2984 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2985 <!-- {{{ is_xsubstr() -->
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 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2988 <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
2989 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2990 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2991 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
2992 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
2993 <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
2994 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
2995 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
2996 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
2997 returns a boolean. The difference between
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
2998 <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
2999 illustrated by the following examples:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3000 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3001 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3002 cdl_option MAGIC {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3003 flavor data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3004 default_value { "abracadabra" }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3005 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3006 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3007 requires { is_substr(MAGIC, " abra") }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3008 requires { is_xsubstr(MAGIC, " abra") }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3009 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3010 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3011 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
3012 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
3013 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
3014 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
3015 <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
3016 does give an exact match.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3017 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3018 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3019 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3020
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3021 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3022 <!-- {{{ version_cmp() -->
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 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3025 <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
3026 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3027 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3028 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
3029 <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
3030 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
3031 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
3032 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
3033 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
3034 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
3035 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
3036 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
3037 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
3038 available in version 1.3:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3039 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3040 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3041 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
3042 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3043 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3044 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3045
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3046 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3047
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 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3050 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3051 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3052 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
3053 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
3054 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
3055 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
3056 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
3057 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
3058 solution automatically.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3059 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3060 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3061
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3062 </sect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3063
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 <!-- {{{ Goal expressions -->
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 <sect2 id="language.goal-expression">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3068 <title>Goal Expressions</title>
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 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3071 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
3072 &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
3073 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
3074 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
3075 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
3076 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
3077 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
3078 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3079 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3080 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
3081 expressions, for example:
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 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3084 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
3085 !CYGDBG_HAL_DEBUG_GDB_BREAK_SUPPORT
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3086 !CYGDBG_HAL_DEBUG_GDB_CTRLC_SUPPORT }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3087 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3088 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3089 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
3090 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
3091 as:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3092 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3093 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3094 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
3095 !CYGDBG_HAL_DEBUG_GDB_BREAK_SUPPORT &&
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3096 !CYGDBG_HAL_DEBUG_GDB_CTRLC_SUPPORT }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3097 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3098 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3099 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
3100 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3101 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3102 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
3103 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
3104 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
3105 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3106 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3107 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
3108 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
3109 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
3110 to cutting and pasting.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3111 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3112 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3113 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
3114 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
3115 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
3116 true.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3117 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3118 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3119 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
3120 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
3121 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
3122 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
3123 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
3124 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
3125 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
3126 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3127 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3128 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
3129 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
3130 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
3131 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
3132 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
3133 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
3134 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
3135 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
3136 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
3137 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
3138 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
3139 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
3140 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
3141 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
3142 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
3143 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
3144 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
3145 behavior.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3146 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3147 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3148 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
3149 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3150 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3151 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
3152 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3153 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3154 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
3155 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3156 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3157 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
3158 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
3159 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3160 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3161 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
3162 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
3163 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
3164 confusion.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3165 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3166
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3167 </sect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3168
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3169 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3170 <!-- {{{ List expressions -->
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 <sect2 id="language.list-expression">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3173 <title>List Expressions</title>
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 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3176 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
3177 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
3178 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
3179 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
3180 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
3181 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
3182 just a single argument.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3183 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3184 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3185 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
3186 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3187 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3188 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
3189 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
3190 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3191 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3192 <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
3193 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
3194 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
3195 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
3196 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
3197 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
3198 <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
3199 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
3200 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
3201 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
3202 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
3203 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
3204 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
3205 examples illustrate these possibilities:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3206 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3207 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3208 legal_values { "red" "green" "blue" }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3209 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
3210 legal_values 1 to CYGARC_MAXINT
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3211 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
3212 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3213 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3214 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
3215 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3216 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3217 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
3218 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3219 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3220 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
3221 <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
3222 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
3223 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
3224 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
3225 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3226 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3227 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
3228 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
3229 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
3230 expression may however give unexpected results.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3231 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3232 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3233 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
3234 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
3235 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
3236 <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
3237 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
3238 <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
3239 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
3240 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
3241 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3242 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3243 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
3244 the following hypothetical example:
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 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3247 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
3248 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3249 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3250 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
3251 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3252 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3253 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
3254 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
3255 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3256 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3257 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
3258 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
3259 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
3260 use brackets and avoid possible confusion.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3261 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3262
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3263 </sect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3264
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 </sect1>
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 <!-- {{{ Interfaces -->
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 <!-- 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
3272 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
3273 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
3274 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
3275 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
3276
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3277 <sect1 id="language.interface">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3278 <title>Interfaces</title>
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 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3281 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
3282 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
3283 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
3284 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
3285 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
3286 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
3287 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
3288 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
3289 dependency might be:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3290 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3291 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3292 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
3293 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3294 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3295 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
3296 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
3297 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
3298 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
3299 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
3300 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
3301 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3302 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3303 &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
3304 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
3305 &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
3306 <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
3307 <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
3308 is a calculated configuration option:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3309 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3310 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3311 cdl_interface CYGINT_KERNEL_SCHEDULER {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3312 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
3313 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3314 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3315 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3316 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3317 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
3318 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3319 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3320 cdl_option CYGSEM_KERNEL_SCHED_MLQUEUE {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3321 display "Multi-level queue scheduler"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3322 default_value 1
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3323 implements CYGINT_KERNEL_SCHEDULER
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3324 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3325 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3326
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3327 cdl_option CYGSEM_KERNEL_SCHED_BITMAP {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3328 display "Bitmap scheduler"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3329 default_value 0
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3330 implements CYGINT_KERNEL_SCHEDULER
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3331 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3332 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3333 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3334 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3335 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
3336 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
3337 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
3338 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
3339 as:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3340 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3341 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3342 requires CYGINT_KERNEL_SCHEDULER
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3343 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3344 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3345 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
3346 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
3347 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
3348 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
3349 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3350 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3351 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
3352 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
3353 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
3354 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
3355 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
3356 <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
3357 <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
3358 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
3359 <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
3360 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
3361 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
3362 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
3363 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3364 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3365 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
3366 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
3367 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
3368 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
3369 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
3370 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
3371 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
3372 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
3373 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
3374 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3375 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3376 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
3377 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
3378 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
3379 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
3380 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
3381 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
3382 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
3383 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
3384 &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
3385 expressions.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3386 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3387 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3388 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3389 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
3390 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
3391 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
3392 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
3393 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
3394 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
3395 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
3396 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
3397 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
3398 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
3399 also provides the appropriate scheduling functions.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3400 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3401 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3402
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3403 </sect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3404
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 <!-- {{{ Package database -->
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 <sect1 id="language.database">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3409 <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
3410
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3411 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3412 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
3413 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
3414 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
3415 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
3416 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
3417 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
3418 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
3419 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
3420 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
3421 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
3422 repository.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3423 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3424 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3425 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
3426 <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
3427 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
3428 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3429 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3430 package CYGPKG_LIBC {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3431 alias { "C library" libc clib clibrary }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3432 directory language/c/libc
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3433 script libc.cdl
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3434 description "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3435 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
3436 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
3437 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
3438 function main()"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3439 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3440
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3441 package CYGPKG_IO_PCI {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3442 alias { "PCI configuration library" io_pci }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3443 directory io/pci
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3444 script io_pci.cdl
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3445 hardware
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3446 description "
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3447 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
3448 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3449 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3450 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3451 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
3452 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
3453 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
3454 following five commands: <literal>alias</literal>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3455 <literal>directory</literal>, <literal>script</literal>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3456 <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
3457 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3458
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3459 <variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3460 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3461 <term><literal>alias</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3462 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3463 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3464 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
3465 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
3466 <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
3467 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
3468 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
3469 <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
3470 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
3471 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
3472 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3473 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3474 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3475
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3476 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3477 <term><literal>directory</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3478 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3479 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3480 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
3481 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
3482 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
3483 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
3484 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
3485 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
3486 separate locations for one package.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3487 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3488 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3489 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3490
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3491 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3492 <term><literal>script</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3493 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3494 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3495 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
3496 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
3497 &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
3498 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
3499 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
3500 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
3501 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
3502 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
3503 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
3504 useful.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3505 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3506 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3507 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3508
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3509 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3510 <term><literal>hardware</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3511 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3512 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3513 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
3514 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
3515 &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
3516 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3517 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3518 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3519
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3520 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3521 <term><literal>description</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3522 <listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3523 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3524 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
3525 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
3526 be re-used.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3527 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3528 </listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3529 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3530 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3531
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3532 <note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3533 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3534 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
3535 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
3536 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
3537 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
3538 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
3539 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
3540 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
3541 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
3542 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
3543 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
3544 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3545 </note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3546 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3547 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
3548 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
3549 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
3550 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
3551 packages.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3552 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3553
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3554 </sect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3555
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3556 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents:
diff changeset
3557
491
def85e4d96d2 http://dev.scriptics.com/ is now http://www.tcl.tk/
jlarmour
parents: 334
diff changeset
3558 </chapter>