1 <!-- Copyright (C) 2003 Red Hat, Inc. -->
2 <!-- This material may be distributed only subject to the terms -->
3 <!-- and conditions set forth in the Open Publication License, v1.0 -->
4 <!-- or later (the latest version is presently available at -->
5 <!-- http://www.opencontent.org/openpub/). -->
6 <!-- Distribution of the work or derivative of the work in any -->
7 <!-- standard (paper) book form is prohibited unless prior -->
8 <!-- permission is obtained from the copyright holder. -->
12 >Editing an eCos Savefile</TITLE
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="eCos User Guide"
20 HREF="ecos-user-guide.html"><LINK
22 TITLE="Manual Configuration"
23 HREF="manual-configuration.html"><LINK
25 TITLE="Fine-grained Configuration"
26 HREF="fine-grained-configuration.html"><LINK
28 TITLE="Editing the Sources"
29 HREF="editing-the-sources.html"></HEAD
40 SUMMARY="Header navigation table"
57 HREF="fine-grained-configuration.html"
65 >Chapter 28. Manual Configuration</TD
71 HREF="editing-the-sources.html"
85 NAME="EDITING-AN-ECOS-SAVEFILE">Editing an <SPAN
93 > configuration information is held in a single
94 savefile, typically <TT
98 be generated by either the GUI configuration tool or by the
103 normally exists at the top level of the build tree. It is a
104 text file, allowing the various configurations options to be
105 edited inside a suitable text editor or by other programs or
106 scripts, as well as in the GUI config tool.</P
111 > savefile is actually a script in the <SPAN
118 language, so any modifications to the file need to preserve Tcl
119 syntax. For most configuration options, any modifications will be
120 trivial and there is no need to worry about Tcl syntax. For example,
121 changing a 1 to a 0 to disable an option. For more complicated
122 options, for example<TT
124 > CYGDAT_UITRON_TASK_EXTERNS</TT
126 which involves some lines of C code, more care has
127 to be taken. If an edited savefile is no longer a valid Tcl script
128 then the configuration tools will be unable to read back the data
129 for further processing, for example to generate a build tree. An
130 outline of Tcl syntax is given below. One point worth noting here
131 is that a line that begins with a “#” is
132 usually a comment, and the bulk of an <SPAN
135 > savefile actually consists
136 of such comments, to make it easier to edit.</P
142 NAME="AEN2721">Header</H2
147 > savefile begins with a header, which typically
148 looks something like this:</P
157 ># eCos saved configuration
158 # ---- commands --------------------------------------------------------
159 # This section contains information about the savefile format.
160 # It should not be edited. Any modifications made to this section
161 # may make it impossible for the configuration tools to read
164 cdl_savefile_version 1;
165 cdl_savefile_command cdl_savefile_version {};
166 cdl_savefile_command cdl_savefile_command {};
168 cdl_configuration { description hardware template package };
169 cdl_savefile_command cdl_package { value_source user_value wizard_value inferred_value };
170 cdl_savefile_command cdl_component { value_source user_value wizard_value inferred_value };
171 cdl_savefile_command cdl_option { value_source user_value wizard_value inferred_value };
172 cdl_savefile_command cdl_interface { value_source user_value wizard_value inferred_value };
178 >This section of the savefile is intended for use by the
179 configuration system, and should not be edited. If this
180 section is edited then the various configuration tools may no
181 longer be able to read in the modified savefile.</P
188 NAME="AEN2727">Toplevel Section</H2
190 >The header is followed by a section that defines the
191 configuration as a whole. A typical example would
201 ># ---- toplevel --------------------------------------------------------
202 # This section defines the toplevel configuration object. The only
203 # values that can be changed are the name of the configuration and
204 # the description field. It is not possible to modify the target,
205 # the template or the set of packages simply by editing the lines
206 # below because these changes have wide-ranging effects. Instead
207 # the appropriate tools should be used to make such modifications.
209 cdl_configuration eCos {
210 description ““ ;
212 # These fields should not be modified.
215 package -hardware CYGPKG_HAL_ARM current ;
216 package -hardware CYGPKG_HAL_ARM_PID current ;
217 package -hardware CYGPKG_IO_SERIAL current ;
218 package -template CYGPKG_HAL current ;
219 package -template CYGPKG_IO current ;
220 package -template CYGPKG_INFRA current ;
221 package -template CYGPKG_KERNEL current ;
222 package -template CYGPKG_UITRON current ;
223 package -template CYGPKG_LIBC current ;
224 package -template CYGPKG_LIBM current ;
225 package -template CYGPKG_DEVICES_WALLCLOCK current ;
226 package -template CYGPKG_ERROR current ;
233 >This section allows the configuration tools to reload the
234 various packages that make up the configuration. Most of the information
235 should not be edited. If it is necessary to add a new package or
236 to remove an existing one then the appropriate tools should be used
237 for this, for example:</P
245 CLASS="PROGRAMLISTING"
246 >$ ecosconfig remove CYGPKG_LIBM</PRE
251 >There are two fields which can be edited. Configurations have
252 a name; in this case <SPAN
255 >. They can also have a description, which
256 is some arbitrary text. The configuration tools do not make use
257 of these fields, they exist so that users can store additional information
258 about a configuration.</P
265 NAME="AEN2735">Conflicts Section</H2
267 >The toplevel section is followed by details of all the
268 conflicts (if any) in the configuration, for
278 ># ---- conflicts -------------------------------------------------------
279 # There are 2 conflicts.
281 # option CYGNUM_LIBC_TIME_DST_DEFAULT_OFFSET
282 # Property LegalValues
283 # Illegal current value 100000
284 # Legal values are: -90000 to 90000
286 # option CYGSEM_LIBC_TIME_CLOCK_WORKING
288 # Requires constraint not satisfied: CYGFUN_KERNEL_THREADS_TIMER
294 >When editing a configuration you may end up with something
295 that is invalid. Any problems in the configuration will be reported
296 in the conflicts section. In this case there are two conflicts.
299 >CYGNUM_LIBC_TIME_DST_DEFAULT_OFFSET</TT
301 been given an illegal value: typically this would be fixed by searching
302 for the definition of that option later on in the savefile and modifying
303 the value. The second conflict is more interesting, an unsatisfied <SPAN
310 Configuration options are not independent: disabling some functionality
311 in, say, the kernel, can have an impact elsewhere; in this case
312 the C library. The various dependencies between the options are
313 specified by the component developers and checked by the configuration
314 system. In this case there are two obvious ways in which the conflict could
315 be resolved: re-enabling <TT
317 >CYGFUN_KERNEL_THREADS_TIMER</TT
321 >CYGSEM_LIBC_TIME_CLOCK_WORKING</TT
323 Both of these options will be listed later on in the file.</P
325 >Some care has to be taken when modifying configuration options,
326 to avoid introducing new conflict. For instance it is possible that
327 there might be other options in the system which have a dependency
330 >CYGSEM_LIBC_TIME_CLOCK_WORKING</TT
332 so disabling that option may not be the best way to resolve the
333 conflict. Details of all such dependencies are provided in the appropriate
334 places in the savefile.</P
336 >It is not absolutely required that a configuration be conflict-free
337 before generating a build tree and building <SPAN
341 developers of each component to decide what would happen if an attempt
342 is made to build <SPAN
345 > while there are still conflicts. In serious
346 cases there is likely to be a compile-time failure, or possibly
347 a link-time failure. In less serious cases the system may build
348 happily and the application can be linked with the resulting library,
349 but the component may not quite function as intended - although
350 it may still be good enough for the specific needs of the application.
351 It is also possible that everything builds and links, but once in
352 a while the system will unaccountably crash. Using a configuration
353 that still has conflicts is done entirely at the user’s
361 NAME="AEN2749">Data Section</H2
363 >The bulk of the savefile lists the various packages,
364 components, and options, including their values and the
365 various dependencies. A number of global options come
366 first, especially those related to the build process such
367 as compiler flags. These are followed by the various
368 packages, and the components and options within those
369 packages, in order.</P
371 >Packages, components and options are organized in a
372 hierarchy. If a particular component is disabled then all
373 options and sub-components below it will be inactive: any
374 changes made to these will have no effect. The savefile
375 contains information about the hierarchy in the form of
376 comments, for example:</P
385 >cdl_package CYGPKG_KERNEL ...
387 cdl_component CYGPKG_KERNEL_EXCEPTIONS ...
389 cdl_option CYGSEM_KERNEL_EXCEPTIONS_DECODE ...
390 cdl_option CYGSEM_KERNEL_EXCEPTIONS_GLOBAL ...
392 cdl_component CYGPKG_KERNEL_SCHED ...
394 cdl_option CYGSEM_KERNEL_SCHED_MLQUEUE ...
395 cdl_option CYGSEM_KERNEL_SCHED_BITMAP ...
403 >This corresponds to the following hierarchy:</P
413 CYGPKG_KERNEL_EXCEPTIONS
414 CYGSEM_KERNEL_EXCEPTIONS_DECODE
415 CYGSEM_KERNEL_EXCEPTIONS_GLOBAL
417 CYGSEM_KERNEL_SCHED_MLQUEUE
418 CYGSEM_KERNEL_SCHED_BITMAP
424 >Providing the hierarchy information in this way allows
425 programs or scripts to analyze the savefile and readily
426 determine the hierarchy. It could also be used by a
427 sufficiently powerful editor to support structured editing
431 > savefiles. The information is not used by the
432 configuration tools themselves since they obtain the
433 hierarchy from the original CDL scripts.</P
435 >Each configurable entity is preceded by a comment, of
436 the following form:</P
446 # doc: ref/ecos-ref/ecos-kernel-overview.html#THE-SCHEDULER
447 # The eCos kernel provides a choice of schedulers. In addition
448 # there are a number of configuration options to control the
449 # detailed behaviour of these schedulers.
450 cdl_component CYGPKG_KERNEL_SCHED {
458 >This provides a short textual alias
461 >Kernel schedulers</TT
463 component. If online documentation is available for the
464 configurable entity then this will come next. Finally
465 there is a short description of the entity as a whole. All
466 this information is provided by the component
469 >Each configurable entity takes the form:</P
478 ><type> <name> {
485 >Configurable entities may not be active. This can be either
486 because the parent is disabled or inactive, or because there are
493 > properties. Modifying
494 the value of an inactive entity has no effect on the configuration,
495 so this information is provided first:</P
506 >cdl_option CYGSEM_KERNEL_EXCEPTIONS_DECODE {
507 # This option is not active
508 # The parent CYGPKG_KERNEL_EXCEPTIONS is disabled
514 cdl_option CYGIMP_IDLE_THREAD_YIELD {
515 # This option is not active
516 # ActiveIf constraint: (CYGNUM_KERNEL_SCHED_PRIORITIES == 1)
517 # CYGNUM_KERNEL_SCHED_PRIORITIES == 32
527 >CYGIMP_IDLE_THREAD_YIELD</TT
529 savefile lists the expression that must be satisfied if the option
530 is to be active, followed by the current value of all entities that
531 are referenced in the expression, and finally the result of evaluating
534 >Not all options are directly modifiable in the savefile. First,
535 the value of packages (which is the version of that package loaded
536 into the configuration) cannot be modified here.</P
545 > cdl_package CYGPKG_KERNEL {
546 # Packages cannot be added or removed, nor can their version be changed,
547 # simply by editing their value. Instead the appropriate configuration
548 # should be used to perform these actions.
555 >The version of a package can be changed using e.g.: </P
564 >$ ecosconfig version 1.3 CYGPKG_KERNEL</PRE
569 >Even though a package’s value cannot be modified
570 here, it is still important for the savefile to contain the details.
571 In particular packages may impose constraints on other configurable
572 entities and may be referenced by other configurable entities. Also
573 it would be difficult to understand or extract the configuration’s
574 hierarchy if the packages were not listed in the appropriate places
577 >Some components (or, conceivably, options) do not have any
578 associated data. Typically they serve only to introduce another
579 level in the hierarchy, which can be useful in the context of the
580 GUI configuration tool.</P
589 > cdl_component CYGPKG_HAL_COMMON_INTERRUPTS {
590 # There is no associated value.
596 >Other components or options have a calculated value. These
597 are not user-modifiable, but typically the value will depend on
598 other options which can be modified. Such calculated options can
599 be useful when controlling what gets built or what ends up in the
600 generated configuration header files. A calculated value may also
601 effect other parts of the configuration, for instance, via a <SPAN
616 > cdl_option BUFSIZ {
617 # Calculated value: CYGSEM_LIBC_STDIO_WANT_BUFFERED_IO ? CYGNUM_LIBC_STDIO_BUFSIZE : 0
618 # CYGSEM_LIBC_STDIO_WANT_BUFFERED_IO == 1
619 # CYGNUM_LIBC_STDIO_BUFSIZE == 256
626 >A special type of calculated value is the <SPAN
633 The value of an interface is the number of active and enabled options
640 > that interface. Again the value
641 of an interface cannot be modified directly; only by modifying the
642 options which implement the interface. However, an interface can
643 be referenced by other parts of the configuration. </P
652 >cdl_interface CYGINT_KERNEL_SCHEDULER {
653 # Implemented by CYGSEM_KERNEL_SCHED_MLQUEUE, active, enabled
654 # Implemented by CYGSEM_KERNEL_SCHED_BITMAP, active, disabled
655 # This value cannot be modified here.
657 # Requires: 1 == CYGINT_KERNEL_SCHEDULER
658 # CYGINT_KERNEL_SCHEDULER == 1
671 ># The following properties are affected by this value
672 # interface CYGINT_KERNEL_SCHEDULER
673 # Requires: 1 == CYGINT_KERNEL_SCHEDULER
679 >If the configurable entity is modifiable then there will be
680 lines like the following:</P
690 cdl_option CYGSEM_KERNEL_SCHED_MLQUEUE {
693 # No user value, uncomment the following line to provide one.
695 # value_source default
703 >Configurable entities can have one of four different flavors:
704 none, bool, data and booldata. Flavor none indicates that there
705 is no data associated with the entity, typically it just acts as
706 a placeholder in the overall hierarchy. Flavor bool is the most
707 common, it is a simple yes-or-no choice. Flavor data is for more
708 complicated configuration choices, for instance the size of an array
709 or the name of a device. Flavor booldata is a combination of bool
710 and data: the option can be enabled or disabled, and there is some
711 additional data associated with the option as well.</P
713 >In the above example the user has not modified this particular
714 option, as indicated by the comment and by the commented-out <TT
718 To disable this option the file should be edited to:</P
727 > cdl_option CYGSEM_KERNEL_SCHED_MLQUEUE {
730 # No user value, uncomment the following line to provide one.
732 # value_source default
740 >The comment preceding the <TT
744 > line can be removed if desired, otherwise it
745 will be removed automatically the next time the file is read and
746 updated by the configuration tools.</P
748 >Much the same process should be used for options with the
749 data flavor, for example:</P
759 cdl_option CYGNUM_LIBC_TIME_DST_DEFAULT_OFFSET {
761 # No user value, uncomment the following line to provide one.
763 # value_source default
764 # Default value: 3600
765 # Legal values: -90000 to 90000
771 >can be changed to:</P
780 > cdl_option CYGNUM_LIBC_TIME_DST_DEFAULT_OFFSET {
783 # value_source default
784 # Default value: 3600
785 # Legal values: -90000 to 90000 }; </PRE
790 >Note that the original text provides the default value in
795 on the assumption that the desired new value is likely to be similar
796 to the default value. The <TT
800 does not need to be updated, it will be fixed up if the savefile
801 is fed back into the configuration system and regenerated.</P
803 >For options with the booldata flavor, the <TT
807 needs take two arguments. The first argument is for the boolean
808 part, the second for the data part. For example:</P
818 cdl_component CYGNUM_LIBM_COMPATIBILITY {
820 # No user value, uncomment the following line to provide one.
822 # value_source default
823 # Default value: 1 POSIX
824 # Legal values: “POSIX” “IEEE” “XOPEN” “SVID”
831 >could be changed to:</P
841 cdl_component CYGNUM_LIBM_COMPATIBILITY {
844 # value_source default
845 # Default value: 1 POSIX
846 # Legal values: “POSIX” “IEEE” “XOPEN” “SVID”
853 >or alternatively, if the whole component should be disabled,
864 cdl_component CYGNUM_LIBM_COMPATIBILITY {
867 # value_source default
868 # Default value: 1 POSIX
869 # Legal values: “POSIX” “IEEE” “XOPEN” “SVID”
876 >Some options take values that span multiple lines. An example
886 > cdl_option CYGDAT_UITRON_MEMPOOLVAR_INITIALIZERS {
888 # No user value, uncomment the following line to provide one.
890 # “CYG_UIT_MEMPOOLVAR( vpool1, 2000 ), \\
891 # CYG_UIT_MEMPOOLVAR( vpool2, 2000 ), \\
892 # CYG_UIT_MEMPOOLVAR( vpool3, 2000 ),”
893 # value_source default
895 # “CYG_UIT_MEMPOOLVAR( vpool1, 2000 ), \\
896 # CYG_UIT_MEMPOOLVAR( vpool2, 2000 ), \\
897 # CYG_UIT_MEMPOOLVAR( vpool3, 2000 ),”
903 >Setting a user value for this option involves uncommenting
904 and modifying all relevant lines, for example:</P
913 > cdl_option CYGDAT_UITRON_MEMPOOLVAR_INITIALIZERS {
916 “CYG_UIT_MEMPOOLVAR( vpool1, 4000 ), \\
917 CYG_UIT_MEMPOOLVAR( vpool2, 4000 ),”
918 # value_source default
920 # “CYG_UIT_MEMPOOLVAR( vpool1, 2000 ), \\
921 # CYG_UIT_MEMPOOLVAR( vpool2, 2000 ), \\
922 # CYG_UIT_MEMPOOLVAR( vpool3, 2000 ),”
928 >In such cases appropriate care has to be taken to preserve
929 Tcl syntax, as discussed below.</P
931 >The configuration system has the ability to keep track of
932 several different values for any given option. All options
933 start off with a default value, in other words their value
938 configuration involves conflicts and the configuration
939 system’s inference engine is allowed to resolve these
940 automatically then it may provide an
954 > cdl_option CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT {
956 # No user value, uncomment the following line to provide one.
958 # The inferred value should not be edited directly.
960 # value_source inferred
968 >Inferred values are calculated by the configuration system
969 and should not be edited by the user. If the inferred value is not
970 correct then a user value should be substituted instead:</P
979 > cdl_option CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT {
982 # The inferred value should not be edited directly.
984 # value_source inferred
992 >The inference engine will not override a user value with an
993 inferred one. Making a change like this may well re-introduce a
994 conflict, since the inferred value was only calculated to resolve
995 a conflict. Another run of the inference engine may find a different
996 and more acceptable way of resolving the conflict, but this is not guaranteed
997 and it may be up to the user to examine the various dependencies
998 and work out an acceptable solution.</P
1000 >Inferred values are listed in the savefile because the exact
1001 inferred value may depend on the order in which changes were made
1002 and conflicts were resolved. If the inferred values were absent
1003 then it is possible that reloading a savefile would not exactly
1004 restore the configuration. Default values on the other hand are
1005 entirely deterministic so there is no actual need for the values
1006 to be listed in the savefile. However, the default value can be
1007 very useful information so it is provided in a comment.</P
1009 >Occasionally the user will want to do some experimentation,
1010 and temporarily switch an option from a user value back to a default
1011 or inferred one to see what the effect would be. This could be achieved
1012 by simply commenting out the user value. For instance, if the current
1013 savefile contains:</P
1023 cdl_option CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT {
1026 # The inferred value should not be edited directly.
1036 >then the inferred value could be restored by commenting out
1050 cdl_option CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT {
1053 # The inferred value should not be edited directly.
1063 >This is fine for simple values. However if the value is complicated
1064 then there is a problem: commenting out the <TT
1068 or lines means that the user value becomes invisible to the configuration system,
1069 so if the savefile is loaded and then regenerated the information
1070 will be lost. An alternative approach is to keep the <TT
1074 explicitly set the <TT
1087 > cdl_option CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT {
1090 # The inferred value should not be edited directly.
1092 value_source inferred
1100 >In this case the configuration system will use the inferred
1101 value for the purposes of dependency analysis etc., even though
1102 a user value is present. To restore the user value the <TT
1106 can be commented out again. If there is no explicit <TT
1110 the configuration system will just use the highest priority one:
1111 the user value if it exists; otherwise the inferred value if it
1112 exists; otherwise the default value which always exists.</P
1114 >The default value for an option can be a simple constant,
1115 or it can be an expression involving other options. In the latter
1116 case the expression will be listed, together with the values for
1117 all options referenced in the expression and the current result
1118 of evaluating that expression. This is for informational purposes
1119 only, the default value is always recalculated deterministically
1120 when loading in a savefile.</P
1129 > cdl_option CYGBLD_GLOBAL_COMMAND_PREFIX {
1131 # No user value, uncomment the following line to provide one.
1132 # user_value arm-elf
1133 # value_source default
1134 # Default value: CYGHWR_THUMB ? “thumb-elf” : “arm-elf”
1142 >For options with the data or booldata flavor, there are likely
1143 to be constraints on the possible values. If the value is supposed
1144 to be a number in a given range and a user value of “<TT
1148 >” is provided instead then there
1149 are likely to be compile-time failures. Component developers can
1150 specify constraints on the legal values, and these will be listed
1161 cdl_option X_TLOSS {
1163 # No user value, uncomment the following line to provide one.
1164 # user_value 1.41484755040569E+16
1165 # value_source default
1166 # Default value: 1.41484755040569E+16
1167 # Legal values: 1 to 1e308
1180 >cdl_component CYGNUM_LIBM_COMPATIBILITY {
1182 # No user value, uncomment the following line to provide one.
1183 # user_value 1 POSIX
1184 # value_source default
1185 # Default value: 1 POSIX
1186 # Legal values: “POSIX” “IEEE” “XOPEN” “SVID”
1193 >In some cases the legal values list may be an expression involving
1194 other options. If so then the current values of the referenced options
1195 will be listed, together with the result of evaluating the list
1196 expression, just as for default value expressions.</P
1198 >If an illegal value is provided then this will result in a
1199 conflict, listed in the conflicts section of the savefile. For more
1200 complicated options a simple legal values list is not sufficient
1201 to allow the current value to be validated, and the configuration
1202 system will be unable to flag conflicts. This issue will be addressed in
1203 future releases of the configuration system.</P
1205 >Following the value-related fields for a given option, any <SPAN
1211 > constraints belonging
1212 to this option will be listed. These constraints are only effective
1213 if the option is active and, for bool and booldata flavors, enabled.
1214 If some aspect of <SPAN
1217 > functionality is inactive or disabled then
1218 it cannot impose any constraints on the rest of the system. As usual,
1219 the full expression will be listed followed by the current values
1220 of all options that are referenced and the result of evaluating
1230 > cdl_option CYGSEM_LIBC_TIME_TIME_WORKING {
1232 # Requires: CYGPKG_DEVICES_WALLCLOCK
1233 # CYGPKG_DEVICES_WALLCLOCK == current
1240 >When modifying the value of an option it is useful to know
1241 not only what constraints the option imposes on the rest of the
1242 system but also what other options in the system depend in some
1243 way on this one. The savefile provides this information:</P
1252 >cdl_option CYGFUN_KERNEL_THREADS_TIMER {
1254 # The following properties are affected by this value
1255 # option CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT
1256 # Requires: CYGFUN_KERNEL_THREADS_TIMER
1257 # option CYGIMP_UITRON_STRICT_CONFORMANCE
1258 # Requires: CYGFUN_KERNEL_THREADS_TIMER
1259 # option CYGSEM_LIBC_TIME_CLOCK_WORKING
1260 # Requires: CYGFUN_KERNEL_THREADS_TIMER
1271 NAME="AEN2847">Tcl Syntax</H2
1276 > savefiles are implemented as Tcl scripts, and are read
1277 in by running the data through a standard Tcl interpreter that has
1278 been extended with a small number of additional commands such as <TT
1283 >cdl_configuration</TT
1285 In many cases this is an implementation detail that can be safely
1286 ignored while editing a savefile: simply replacing a <TT
1293 > to disable some functionality
1294 is not going to affect whether or not the savefile is still a valid
1295 Tcl script and can be processed by a Tcl interpreter. However, there
1296 are more complicated cases where an understanding of Tcl syntax
1297 is at least desirable, for example:</P
1306 > cdl_option CYGDAT_UITRON_MEMPOOLVAR_EXTERNS {
1309 “static char vpool1\[ 2000 \], \\
1310 vpool2\[ 2000 \], \\
1311 vpool3\[ 2000 \];”
1312 # value_source default
1314 # “static char vpool1\[ 2000 \], \\
1315 # vpool2\[ 2000 \], \\
1316 # vpool3\[ 2000 \];”
1322 >The backslash at the end of the <TT
1326 is processed by the Tcl interpreter as a line continuation character.
1327 The quote marks around the user data are also interpreted by the
1328 Tcl interpreter and serve to turn the entire data field into a single
1329 argument. The backslashes preceding the opening and closing square
1330 brackets prevent the Tcl interpreter from treating these characters
1331 specially, otherwise there would be an attempt at <SPAN
1338 > as described below. The double backslashes
1339 at the end of each line of the data will be turned into a single
1340 backslash by the Tcl interpreter, rather than escaping the newline
1341 character, so that the actual data seen by the configuration system
1351 > static char vpool1[ 2000 ], \
1353 vpool3[ 2000 ]; </PRE
1358 >This is of course the data that should end up in the µITRON
1359 configuration header file. The opening and closing braces surrounding
1360 the entire body of the option data are also significant and cause
1361 this body to be passed as a single argument to the <B
1365 The closing semicolon is optional in this example, but provides
1366 a small amount of additional robustness if the savefile is edited
1367 such that it is no longer a valid Tcl script. If the data contained
1372 these would have to be treated specially as well, via a backslash escape.</P
1374 >In spite of what all the above might seem to suggest, Tcl
1375 is actually a very simple yet powerful scripting language: the syntax
1376 is defined by just eleven rules. On occasion this simplicity means
1377 that Tcl’s behaviour is subtly different from other languages,
1378 which can confuse newcomers.</P
1380 >When the Tcl interpreter is passed some data such as <TT
1384 >, it splits this data into a command and its
1385 arguments. The command will be terminated by a newline or by a semicolon,
1386 unless one of the quoting mechanisms is used. The command and each
1387 of its arguments are separated by white space. So in the following
1403 >will result in two separate commands being executed. The first
1408 single argument, <TT
1423 The intervening newline character serves to terminate the first
1424 command, and a semi-colon separator could be used instead: </P
1432 CLASS="PROGRAMLISTING"
1433 >puts Hello;set x 42</PRE
1438 >Any white space surrounding the semicolon is just ignored
1439 because it does not serve to separate arguments.</P
1441 >Now consider the following:</P
1450 >set x Hello world</PRE
1455 >This is not valid Tcl. It is an attempt to invoke the <TT
1459 with three arguments: <TT
1473 takes two arguments, a variable name and a value, so it is necessary
1474 to combine the data into a single argument by quoting:</P
1482 CLASS="PROGRAMLISTING"
1483 >set x “Hello world”</PRE
1488 >When the Tcl interpreter encounters the first quote character
1489 it treats all subsequent data up to but not including the closing
1490 quote as part of the current argument. The quote marks are removed
1491 by the interpreter, so the second argument passed to the <TT
1499 quote characters. This can be significant in the context of <SPAN
1503 For instance, consider the following configuration option:</P
1512 > cdl_option CYGDAT_LIBC_STDIO_DEFAULT_CONSOLE {
1514 # No user value, uncomment the following line to provide one.
1515 # user_value “\”/dev/ttydiag\””
1516 # value_source default
1517 # Default value: “\”/dev/ttydiag\””
1523 >The desired value of the configuration option should be a
1524 valid C string, complete with quote characters. If the savefile
1534 > cdl_option CYGDAT_LIBC_STDIO_DEFAULT_CONSOLE {
1536 user_value “/dev/ttydiag”
1537 # value_source default
1538 # Default value: “\”/dev/ttydiag\””
1544 >then the Tcl interpreter would remove the quote marks when
1545 the savefile is read back in, so the option’s value would
1546 not have any quote marks and would not be a valid C string. The
1547 configuration system is not yet able to perform the required validation
1548 so the following <TT
1552 be generated in the configuration header file:</P
1560 CLASS="PROGRAMLISTING"
1561 >#define CYGDAT_LIBC_STDIO_DEFAULT_CONSOLE /dev/ttydiag </PRE
1566 >This is likely to cause a compile-time failure when building
1572 >A quoted argument continues until the closing quote character
1573 is encountered, which means that it can span multiple lines. This
1574 can also be encountered in <SPAN
1577 > savefiles, for instance, in the <TT
1579 >CYGDAT_UITRON_MEMPOOLVAR_EXTERNS</TT
1581 mentioned earlier. Newline or semicolon characters do not terminate
1582 the current command in such cases.</P
1584 >The Tcl interpreter supports much the same forms of backslash
1585 substitution as other common programming languages. Some backslash
1586 sequences such as <TT
1590 be replaced by the appropriate character. The sequence <TT
1594 be replaced by a single backslash. A backslash at the very end of
1595 a line will cause that backslash, the newline character, and any
1596 white space at the start of the next line to be replaced by a single
1597 space. Hence the following two Tcl commands are equivalent:</P
1605 CLASS="PROGRAMLISTING"
1606 >puts “Hello\nworld\n”
1615 >In addition to quote and backslash characters, the Tcl interpreter
1616 treats square brackets, the <TT
1620 and braces specially. Square brackets are used for command substitution,
1629 CLASS="PROGRAMLISTING"
1630 >puts “The answer is [expr 6 * 9]”</PRE
1635 >When the Tcl interpreter encounters the square brackets it
1636 will treat the contents as another command that should be executed
1637 first, and the result of executing that is used when continuing
1638 to process the script. In this case the Tcl interpreter will execute
1643 yielding a result of 54, and then the Tcl interpreter will execute
1646 >puts “The answer is 54”</TT
1647 >. It should be noted that
1648 the interpreter contains only one level of substitution: if the
1649 result of performing command substitution performs further special
1650 characters such as square brackets then these will not be treated
1653 >Command line substitution is very unlikely to prove useful
1654 in the context of an <SPAN
1657 > savefile, but it is part of the Tcl language
1658 and hence cannot be easily suppressed while reading in a savefile.
1659 As a result care has to be taken when savefile data involves square
1660 brackets. Consider the following:</P
1668 CLASS="PROGRAMLISTING"
1669 > cdl_option CYGDAT_UITRON_MEMPOOLFIXED_EXTERNS {
1672 “static char fpool1[ 2000 ],
1673 fpool2[ 2000 ];”
1680 >The Tcl interpreter will interpret the square brackets as
1681 an attempt at command substitution and hence it will attempt to
1682 execute the command <TT
1686 arguments. No such command is defined by the Tcl language or by
1687 the savefile-related extensions provided by the configuration system,
1688 so this will result in an error when an attempt is made to read
1689 back the savefile. Instead it is necessary to backslash-escape the
1690 square brackets and thus suppress command substitution:</P
1698 CLASS="PROGRAMLISTING"
1699 > cdl_option CYGDAT_UITRON_MEMPOOLFIXED_EXTERNS {
1702 “static char fpool1\[ 2000 \],
1703 fpool2\[ 2000 \];”
1714 is used in Tcl scripts to perform variable substitution:</P
1722 CLASS="PROGRAMLISTING"
1724 puts “The answer is $x” </PRE
1729 >Variable substitution, like command substitution, is very
1730 unlikely to prove useful in the context of an <SPAN
1734 it be necessary to have a <TT
1738 in configuration data then again a backslash escape needs to be
1747 CLASS="PROGRAMLISTING"
1748 >cdl_option FOODAT_MONITOR_PROMPT {
1750 user_value “\$ “
1757 >Braces are used to collect a sequence of characters into a
1758 single argument, just like quotes. The difference is that variable,
1759 command and backslash substitution do not occur inside braces (with
1760 the sole exception of backslash substitution at the end of a line).
1761 So, for example, the <TT
1763 >CYGDAT_UITRON_MEMPOOL_EXTERNFIXED_EXTERNS</TT
1765 could be written as:</P
1773 CLASS="PROGRAMLISTING"
1774 >cdl_option CYGDAT_UITRON_MEMPOOLFIXED_EXTERNS {
1777 {static char fpool1[ 2000 ],
1785 >The configuration system does not use this when generating
1786 savefiles because for simple edits of a savefile by inexperienced
1787 users the use of brace characters is likely to be a little bit more
1788 confusing than the use of quotes.</P
1790 >At this stage it is worth noting that the basic format of
1791 each configuration option in the savefile makes use of braces:</P
1799 CLASS="PROGRAMLISTING"
1800 >cdl_option <name> {
1807 >The configuration system extends the Tcl language with a small
1808 number of additional commands such as <TT
1812 These commands take two arguments, a name and a body, where the
1813 body consists of all the text between the braces. First a check
1814 is made that the specified option is actually present in the configuration.
1815 Then the body is executed in a recursive invocation of the Tcl interpreter,
1816 this time with additional commands such as <TT
1823 If, after editing, the braces are not correctly matched up then
1824 the savefile will no longer be a valid Tcl script and errors will
1825 be reported when the savefile is loaded again.</P
1827 >Comments in Tcl scripts are introduced by a hash character <TT
1831 However, a hash character only introduces a comment if it occurs
1832 where a command is expected. Consider the following:</P
1840 CLASS="PROGRAMLISTING"
1841 ># This is a comment
1842 puts “Hello” # world </PRE
1847 >The first line is a valid comment, since the hash character
1848 occurs right at the start where a command name is expected. The
1849 second line does not contain a comment. Instead it is an attempt
1854 three arguments: <TT
1864 These are not valid arguments for the <TT
1868 so an error will be raised.</P
1870 >If the second line was rewritten as:</P
1878 CLASS="PROGRAMLISTING"
1879 >puts “Hello”; # world</PRE
1884 >then this is a valid Tcl script. The semicolon identifies
1885 the end of the current command, so the hash character occurs at
1886 a point where the next command would start and hence it is interpreted
1887 as the start of a comment.</P
1889 >This handling of comments can lead to subtle behaviour. Consider
1898 CLASS="PROGRAMLISTING"
1899 >cdl_option WHATEVER {
1900 # This is a comment }
1908 >Consider the way the Tcl interpreter processes this. The command
1909 name and the first argument do not pose any special difficulties.
1910 The opening brace is interpreted as the start of the next argument,
1911 which continues until a closing brace is encountered. In this case
1912 the closing brace occurs on the second line, so the second argument
1918 >\n # This is a comment</TT
1919 > . This second argument
1920 is processed in a recursive invocation of the Tcl interpreter and
1921 does not contain any commands, just a comment. Toplevel savefile
1922 processing then resumes, and the next command that is encountered
1927 relevant savefile code is not currently processing a configuration
1928 option this is an error. Later on the Tcl interpreter would encounter
1929 a closing brace by itself, which is also an error. Fortunately this
1930 sequence of events is very unlikely to occur when editing generated
1933 >This should be sufficient information about Tcl to allow for
1934 safe editing of <SPAN
1937 > savefiles. Further information is available
1938 from a wide variety of sources, for example the book <SPAN
1943 and the Tk Toolkit </I
1945 >by John K Ousterhout.</P
1953 SUMMARY="Footer navigation table"
1964 HREF="fine-grained-configuration.html"
1973 HREF="ecos-user-guide.html"
1982 HREF="editing-the-sources.html"
1992 >Fine-grained Configuration</TD
1998 HREF="manual-configuration.html"
2006 >Editing the Sources</TD
projects / karo-tx-redboot.git / blob