3 <!-- =============================================================== -->
5 <!-- configuration.sgml -->
7 <!-- eCos User Guide -->
9 <!-- =============================================================== -->
10 <!-- ####COPYRIGHTBEGIN#### -->
12 <!-- =============================================================== -->
13 <!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Red Hat, Inc. -->
14 <!-- This material may be distributed only subject to the terms -->
15 <!-- and conditions set forth in the Open Publication License, v1.0 -->
16 <!-- or later (the latest version is presently available at -->
17 <!-- http://www.opencontent.org/openpub/) -->
18 <!-- Distribution of the work or derivative of the work in any -->
19 <!-- standard (paper) book form is prohibited unless prior -->
20 <!-- permission obtained from the copyright holder -->
21 <!-- =============================================================== -->
23 <!-- ####COPYRIGHTEND#### -->
24 <!-- =============================================================== -->
25 <!-- #####DESCRIPTIONBEGIN#### -->
27 <!-- ####DESCRIPTIONEND#### -->
28 <!-- =============================================================== -->
32 <PART id="configuration-and-the-package-repository">
33 <TITLE>Configuration and the Package Repository</TITLE>
35 <PARA>The following chapters contain information on running
36 <COMMAND>ecosconfig</COMMAND> (the command line tool that
37 manipulates configurations and constructs build trees) and on
38 managing a source repository across multiple versions of
39 <productname>eCos</productname>. </PARA>
41 <CHAPTER id="manual-configuration">
42 <TITLE>Manual Configuration</TITLE>
44 <PARA><productname>eCos</productname> developers will generally use the graphical
45 Configuration Tool for configuring an <productname>eCos</productname> system and building
46 the target library. However, some user prefer to use command
47 line tools. These command line tools can also be used for batch
48 operations on all platforms, for example as part of a nightly
49 rebuild and testing procedure.
52 <PARA>In the current release of the system the command line tools
53 do not provide exactly the same functionality as the graphical
54 tool. Most importantly, there is no facility to resolve
55 configuration conflicts interactively.</PARA>
56 <PARA>The <productname>eCos</productname> configuration system, both graphical and command
57 line tools, are under constant development and enhancement.
58 Developers should note that the procedures described may change
59 considerably in future releases. </PARA>
61 <SECT1 id="directory-tree-structure">
62 <TITLE>Directory Tree Structure</TITLE>
63 <PARA>When building <productname>eCos</productname> there are three main directory trees to
64 consider: the source tree, the build tree, and the install
66 <PARA>The source tree, also known as the component repository,
67 is read-only. It is possible to use a single component
68 repository for any number of different configurations, and
69 it is also possible to share a component repository between
70 multiple users by putting it on a network drive.</PARA>
71 <PARA>The build tree contains everything that is specific to a
72 particular configuration, including header and other files
73 that contain configuration data, and the object files that
74 result from compiling the system sources for this
75 configuration. </PARA>
76 <PARA>The install tree is usually located in the <filename>install</filename> subdirectory
77 of the build tree. Once an <productname>eCos</productname> system has been built, the install
78 tree contains all the files needed for application development including
79 the header files and the target library. By making copies of the
80 install tree after a build it is possible to separate application
81 development and system configuration, which may be desirable for
82 some organizations. </PARA>
85 <SECT1 id="creating-build-tree">
86 <TITLE>Creating the Build Tree</TITLE>
87 <PARA>Generating a build tree is a non-trivial operation and
88 should not be attempted manually. Instead, <productname>eCos</productname> is shipped
89 with a tool called <COMMAND>ecosconfig</COMMAND> that should
90 be used to create a build tree.</PARA>
91 <PARA>Usually <command>ecosconfig</command> will be
92 run inside the build tree itself. If you are creating a new build
93 tree then typically you will create a new empty directory using
94 the <command>mkdir</command> command, <command>cd</command> into
95 that directory, and then invoke <command>ecosconfig</command> to
96 create a configuration. By default, the configuration is stored
97 in a file <filename>ecos.ecc</filename> in the current
98 directory. The configuration may be modified by editing this file directly. <command>ecosconfig</command> itself
99 deals with a number of coarse-grained configuration options such
100 as the target platform and the packages that should be used.</PARA>
101 <PARA>The <command>ecosconfig</command> tool is also
102 used subsequently to generate a build tree for a configuration.
103 Once a build tree exists, it is possible to run <command>ecosconfig</command> again
104 inside the same build tree. This will be necessary if your wish
105 to change some of the configuration options.</PARA>
106 <PARA><COMMAND>ecosconfig</COMMAND> does not generate
107 the top-level directory of the build tree; you must do this
109 <SCREEN>$ mkdir ecos-work
110 $ cd ecos-work</SCREEN>
111 <PARA>The next step is to run <COMMAND>ecosconfig</COMMAND>: </PARA>
112 <SCREEN>$ ecosconfig <qualifiers> <command></SCREEN>
114 <TITLE>ecosconfig qualifiers</TITLE>
115 <PARA>The available command line qualifiers for
116 <COMMAND>ecosconfig</COMMAND> are as follows. Multiple
117 qualifiers may be used on the command line:
121 <TERM><OPTION>--help</OPTION></TERM>
123 <PARA>Provides basic usage guidelines for the
124 available commands and qualifiers.</PARA>
128 <TERM><OPTION>--config=<file></OPTION></TERM>
130 <PARA>Specifies an <productname>eCos</productname> configuration save file for
131 use by the tool. By default, the file
132 <filename>ecos.ecc</filename> in the
133 current directory is used. Developers may prefer to
134 use a common location for all their <productname>eCos</productname>
135 configurations rather than keep the configuration
136 information in the base of the build tree.</PARA>
140 <TERM><OPTION>--prefix=<dir></OPTION></TERM>
142 <PARA>Specifies an alternative location for the
143 install tree. By default, the install tree resides
144 inside the <filename>install</filename>
145 directory in the build tree. Developers may prefer
146 to locate the build tree in a temporary file
147 hierarchy but keep the install tree in a more
148 permanent location.</PARA>
152 <TERM><OPTION>--srcdir=<dir></OPTION></TERM>
154 <PARA>Specifies the location of the component
155 repository. By default, the tool uses the location
157 <REPLACEABLE>ECOS_REPOSITORY</REPLACEABLE>
158 environment variable. Developers may prefer to use
159 of this qualifier if they are working with more than
160 one repository.</PARA>
164 <TERM><OPTION>--no-resolve</OPTION></TERM>
166 <PARA>Disables the implicit resolution of conflicts
167 while manipulating the configuration data.
168 developers may prefer to resolve conflicts by
169 editing the <productname>eCos</productname> configuration save file
174 <TERM><OPTION>--ignore-errors</OPTION></TERM>
175 <TERM><OPTION>-i</OPTION></TERM>
178 By default, ecosconfig will exit with an error code if the current
179 configuration contains any conflicts, and it is not possible to
180 generate or update a build tree for such configurations. This
181 qualifier causes ecosconfig to ignore such problems, and hence it is
182 possible to generate a build tree even if there are still
183 conflicts. Of course, there are no guarantees that the resulting
184 system will actually do anything.
189 <TERM><OPTION>--verbose</OPTION></TERM>
190 <TERM><OPTION>-v</OPTION></TERM>
193 Display more information.
198 <TERM><OPTION>--quiet</OPTION></TERM>
199 <TERM><OPTION>-q</OPTION></TERM>
202 Display less information.
208 The <OPTION>--config</OPTION>, <OPTION>--prefix</OPTION> and
209 <OPTION>--srcdir</OPTION> qualifiers can also be written with two arguments,
213 ecosconfig --srcdir <REPLACEABLE><dir></REPLACEABLE> ...
216 This simplifies filename completion with some shells.
220 <TITLE>ecosconfig commands</TITLE>
221 <PARA>The available commands for
222 <COMMAND>ecosconfig</COMMAND> are as
226 <TERM><COMMAND>list</COMMAND></TERM>
228 <PARA>Lists the available packages, targets and
229 templates as installed in the <productname>eCos</productname> repository.
230 Aliases and package versions are also
235 <TERM><COMMAND>new <target> [<template> [<version>]]</COMMAND></TERM>
237 <PARA>Creates a new <productname>eCos</productname> configuration for
238 the specified target hardware and saves it. A
239 software template may also be specified. By default,
240 the template named ‘default’ is used. If
241 the template version is not specified, the latest
242 version is used.</PARA>
246 <TERM><COMMAND>target <target></COMMAND></TERM>
248 <PARA>Changes the target hardware selection
249 for the <productname>eCos</productname> configuration. This has the effect of
250 unloading packages supporting the target selected
251 previously and loading the packages which support
252 the new hardware. This command will be used
253 typically when switching between a simulator and
254 real hardware.</PARA>
258 <TERM><COMMAND>template <template> [<version>]</COMMAND></TERM>
260 <PARA>Changes the template selection for the <productname>eCos</productname>
261 configuration. This has the effect of unloading
262 packages specified by the template selected
263 previously and loading the packages specified by the
264 new template. By default, the latest version of the
265 specified template is used.</PARA>
269 <TERM><COMMAND>remove <packages></COMMAND></TERM>
271 <PARA>Removes the specified packages from the <productname>eCos</productname>
272 configuration. This command will be used typically
273 when the template on which a configuration is based
274 contains packages which are not required.</PARA>
278 <TERM><COMMAND>add <packages></COMMAND></TERM>
280 <PARA>Adds the specified packages to the <productname>eCos</productname> configuration. This
281 command will be used typically when the template on which a
282 configuration is based does not contain all the packages which are
283 required.For example, add-on packages provided by third parties will
284 not be known to the standard templates, so they will have to be added
289 <TERM><COMMAND>version <version> <packages></COMMAND></TERM>
291 <PARA>Selects the specified version of a
292 number of packages in the <productname>eCos</productname> configuration. By
293 default, the most recent version of each package is
294 used. This command will be used typically when an
295 older version of a package is required.</PARA>
299 <TERM><COMMAND>check</COMMAND></TERM>
301 <PARA>Presents the following information
302 concerning the current configuration:</PARA>
305 <PARA>the selected target hardware</PARA>
308 <PARA>the selected template</PARA>
311 <PARA>additional packages</PARA>
314 <PARA>removed packages</PARA>
317 <PARA>the selected version of packages
318 where this is not the most recent
322 <PARA>conflicts in the current configuration</PARA>
328 <TERM><COMMAND>resolve</COMMAND></TERM>
330 <PARA>Resolves conflicts identified in the
331 current <productname>eCos</productname> configuration by invoking an inference
332 capability. Resolved conflicts are reported, but not
333 all conflicts may be resolvable. This command will
334 be used typically following manual editing of the
335 configuration.</PARA>
339 <TERM><COMMAND>export <file></COMMAND></TERM>
341 <PARA>Exports a minimal <productname>eCos</productname> configuration
342 save file with the specified name. This file
343 contains only those options which do not have their
344 default value. Such files are used typically to
345 transfer option values from one configuration to
350 <TERM><COMMAND>import <file></COMMAND></TERM>
352 <PARA>Imports a minimal <productname>eCos</productname> configuration
353 save file with the specified name. The values of
354 those options specified in the file are applied to
355 the current configuration.</PARA>
359 <TERM><COMMAND>tree</COMMAND></TERM>
361 <PARA>Generates a build tree based on the current <productname>eCos</productname>
362 configuration. This command will be used typically
363 just before building <productname>eCos</productname>.Normally a build tree can
364 only be generated if if the configuration has no unresolved
365 conflicts, but <OPTION>--ignore-errors</OPTION> can be used to override
372 <SECT1 id="conflicts-and-constraints">
373 <TITLE>Conflicts and constraints</TITLE>
374 <PARA>Configuration options are not completely independent. For example
375 the C library's <FUNCTION>strtod()</FUNCTION> and <FUNCTION>atof()</FUNCTION>
376 functions rely on the math library package to provide certain functionality. If the math library package is removed then the C
377 library can no longer provide these functions. Each package describes constraints like these in CDL <EMPHASIS>"requires"</EMPHASIS> properties. If a constraint is not satisfied, then the configuration contains a conflict. For any given conflict there can
378 be several resolution options. For example, it would be possible to add the math library package back to the
379 configuration, or to disable the <FUNCTION>strtod()</FUNCTION> and <FUNCTION>atof()</FUNCTION> functions.</PARA>
381 The <productname>eCos</productname> configuration tools will report any conflicts in the current configuration. If there are any such conflicts
382 then the configuration is usually unsafe and it makes no sense to build and run <productname>eCos</productname> in such circumstances. In fact,
383 any attempt at building <productname>eCos</productname> is likely to fail. In exceptional cases it is possible to override this by using e.g. the
384 <OPTION>--ignore-errors</OPTION> qualifier with ecosconfig.
387 Many constraints are fairly simple in nature, and the configuration tools contain an inference engine which can
388 resolve the associated conflicts automatically. For example, if the math library package is removed then the
389 inference engine can resolve the resulting conflict by disabling the configuration option for <FUNCTION>strtod()</FUNCTION> and <FUNCTION>atof()</FUNCTION>. All
390 such changes will be reported. Sometimes the inference engine cannot resolve a conflict, for example it is not
391 allowed to override a change that has been made explicitly by the user. Sometimes it will find a solution which does
392 not match the application's requirements.
395 A typical session involving conflicts would look something like this:
398 </SCREEN>This creates a new configuration with the default template. For most targets this will not result in any conflicts,
399 because the default settings for the various options meet the requirements of the default template.
400 </PARA><PARA> For some targets
401 there may be conflicts and the inference engine would come into play.
403 $ ecosconfig remove libm
404 U CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT, new inferred value 0
405 U CYGFUN_LIBC_strtod, new inferred value 0
406 U CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT, new inferred value 0
408 ecosconfig reports that this change caused three conflicts, all in the C library. The inference engine was able to
409 resolve all the conflicts and update the relevant configuration options accordingly. </PARA>
410 <PARA>To suppress the inference engine <OPTION>--no-resolve</OPTION> can be used:
413 $ ecosconfig --no-resolve remove libm
414 C CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT, "requires" constraint not satisfied: CYGPKG_LIBM
415 C CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT, "requires" constraint not satisfied: CYGPKG_LIBM
416 C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM
418 Three unresolved conflicts are reported.
420 <PARA>The <COMMAND>check</COMMAND> command can be used to get the current state of the
421 configuration, and the <OPTION>--verbose</OPTION> qualifier will provide additional information: </PARA>
423 $ ecosconfig --srcdir /home/bartv/ecc/ecc --verbose check
429 C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM
431 CYGFUN_LIBC_strtod -> 0
432 CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT -> 0
433 C CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT, "requires" constraint not satisfied: CYGPKG_LIBM
435 CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT -> 0
436 C CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT, "requires" constraint not satisfied: CYGPKG_LIBM
438 CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT -> 0
441 If the proposed solutions are acceptable, the resolve command can be used to apply them:
444 U CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT, new inferred value 0
445 U CYGFUN_LIBC_strtod, new inferred value 0
446 U CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT, new inferred value 0
448 <PARA>The current configuration is again conflict-free and it is possible to generate a build tree. The <OPTION>--quiet</OPTION> qualifier can
449 be used to suppress the change messages, if desired.
451 When changing individual configuration options by editing the ecos.ecc file (as described below), the resulting
452 system should be checked and any problems should be resolved. For example, if CYGFUN_LIBC_strtod is
453 explicitly enabled in the savefile:
462 C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM
464 C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM
466 In this case the inference engine cannot resolve the conflict automatically because that would involve changing a
467 user setting. Any attempt to generate a build tree will fail:
469 $ ecosconfig --srcdir /home/bartv/ecc/ecc tree
470 C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM
471 Unable to generate build tree, this configuration still contains conflicts.
472 Either resolve the conflicts or use --ignore-errors
475 It is still possible to generate a build tree:
477 $ ecosconfig --srcdir /home/bartv/ecc/ecc --ignore-errors tree
478 C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM
481 In this case <productname>eCos</productname> will fail to build. In other cases of unresolved conflicts <productname>eCos</productname> may build, but may not run. In
482 general all conflicts should be resolved by editing the <FILENAME>ecos.ecc</FILENAME> file, by letting the inference engine make appropriate
483 changes, or by other means, before any attempt is made to build or run <productname>eCos</productname>.
486 <SECT1 id="building-the-system">
487 <TITLE>Building the System</TITLE>
488 <PARA>Once a build tree has been generated with
489 <COMMAND>ecosconfig</COMMAND>, <!-- <index></index>
490 -->building <productname>eCos</productname> is straightforward:</PARA>
491 <SCREEN>$ make</SCREEN>
492 <PARA>The build tree contains the subdirectories, makefiles,
493 and everything else that is needed to generate the default
494 configuration for the selected architecture and platform.
495 The only requirement is that the tools needed for that
496 architecture, for example
497 <COMMAND>powerpc-eabi-g++</COMMAND>,
498 are available using the standard search path. If this is not
499 the case then the <COMMAND>make</COMMAND> will
500 fail with an error message. If you have a multiprocessor
501 system then it may be more efficient to use:</PARA>
502 <SCREEN>$ make -j <REPLACEABLE>n</REPLACEABLE></SCREEN>
503 <PARA>where <REPLACEABLE>n</REPLACEABLE> is equal to the
504 number of processors on your system.</PARA>
505 <PARA>Once the <COMMAND>make</COMMAND> process
506 has completed, the install tree will contain the header
507 files and the target library that are needed for application
509 <PARA>It is also possible to build the system’s test cases
510 for the current configuration:</PARA>
511 <SCREEN>$ make tests</SCREEN>
512 <PARA>The resulting test executables will end up in a
513 <FILENAME>tests</FILENAME> subdirectory of the
514 <!-- <index></index> -->install tree. </PARA>
515 <PARA>If disk space is scarce then it is possible to make the copy
516 of the install tree for application development purposes, and then
518 <SCREEN>$ make clean</SCREEN>
519 <PARA>The build tree will now use up a minimum of disk space — the
520 bulk of what is left consists of configuration header files that
521 you may have edited and hence should not be deleted automatically.
522 However, it is possible to rebuild the system at any time without
523 re-invoking <COMMAND>ecosconfig</COMMAND>, just by
524 running <COMMAND>make</COMMAND> again. </PARA>
525 <PARA>Under exceptional circumstances it may be necessary to run <COMMAND>make
526 clean</COMMAND> for other reasons, such as when a new release
527 of the toolchain is installed. The toolchain includes a number of
528 header files which are closely tied to the compiler, for example <filename>limits.h</filename>,
529 and these header files are not and should not be duplicated by <productname>eCos</productname>.
530 The makefiles perform header file dependency analysis, so that when
531 a header file is changed all affected sources will be rebuilt during
532 the next <COMMAND>make</COMMAND>. This is very useful
533 when the configuration header files are changed, but it also means
534 that a build tree containing information about the locations of
535 header files must be rebuilt. If a new version of the toolchain
536 is installed and the old version is removed then this location information
537 is no longer accurate, and <COMMAND>make</COMMAND> will
538 complain that certain dependencies cannot be satisfied. Under such circumstances
539 it is necessary to do a <COMMAND>make clean</COMMAND> first. </PARA>
541 <SECT1 id="ecos-packages">
542 <TITLE>Packages</TITLE>
543 <PARA><productname>eCos</productname> is a component architecture. The system comes as a
544 number of <!-- <index></index> -->packages which can be
545 enabled or disabled as required, and new packages can be
546 added as they become available. Unfortunately, the packages
547 are not completely independent: for example the µITRON
548 compatibility package relies almost entirely on
549 functionality provided by the kernel package, and it would
550 not make sense to try to build µITRON if the kernel
551 was disabled. The C library has fewer dependencies: some
552 parts of the C library rely on kernel functionality, but it
553 is possible to disable these parts and thus build a system
554 that has the C library but no kernel. The
555 <command>ecosconfig</command> tool has the capability of
556 checking that all the dependencies are satisfied, but it
557 may still be possible to produce configurations that will
558 not build or (conceivably) that will build but not run.
559 Developers should be aware of this and take appropriate
561 <PARA>By default, <!-- <index></index> --><command>ecosconfig</command> will
562 include all packages that are appropriate for the specified hardware
563 in the configuration. The common <!-- <index></index> -->HAL package and
564 the <productname>eCos</productname> infrastructure must be present in every configuration. In
565 addition, it is always necessary to have one architectural HAL package
566 and one platform HAL package. Other packages are optional, and can
567 be added or removed from a configuration as required.</PARA>
568 <PARA>The application may not require all of the packages; for example,
569 it might not need the µITRON compatibility
570 package, or the floating point support provided by the math library.
571 There is a slight overhead when <productname>eCos</productname> is built because the packages
572 will get compiled, and there is also a small disk space penalty.
573 However, any unused facilities will get stripped out at link-time,
574 so having redundant packages will not affect the final executable. </PARA>
576 <SECT1 id="coarse-grained-configuration">
577 <TITLE>Coarse-grained Configuration</TITLE>
578 <PARA>Coarse-grained <!-- <index></index> -->configuration of
579 an <productname>eCos</productname> system means making configuration changes using the
580 <COMMAND>ecosconfig</COMMAND> tool. These changes
584 <PARA>switching to different target hardware</PARA>
587 <PARA>switching to a different template</PARA>
590 <PARA>adding or removing a package</PARA>
593 <PARA>changing the version of a package</PARA>
596 <PARA>Whenever <COMMAND>ecosconfig</COMMAND> generates or
597 updates an <productname>eCos</productname> configuration, it generates a configuration
599 <PARA>Suppose that the configuration was first created using
600 the following command line: </PARA>
601 <SCREEN>$ ecosconfig new stdeval1</SCREEN>
602 <PARA>To change the target hardware to the Cogent CMA28x
603 PowerPC board, the following command would be needed:
605 <SCREEN>$ ecosconfig target cma28x</SCREEN>
606 <PARA>To switch to the PowerPC simulator instead: </PARA>
607 <SCREEN>$ ecosconfig target psim</SCREEN>
608 <PARA>As the hardware changes, hardware-related packages such as
609 the HAL packages and device drivers will be added to and removed
610 from the configuration as appropriate. </PARA>
611 <PARA>To remove any package from the current configuration, use
612 the <COMMAND>remove</COMMAND> command: </PARA>
613 <SCREEN>$ ecosconfig remove uitron</SCREEN>
614 <PARA>You can disable multiple packages using multiple arguments,
616 <SCREEN>$ ecosconfig remove uitron libm</SCREEN>
617 <PARA>If this turns out to have been a mistake then you can
618 re-enable one or more packages with the
619 <COMMAND>add</COMMAND> command: </PARA>
620 <SCREEN>$ ecosconfig add libm</SCREEN>
621 <PARA>Changing the desired version for a package is also
622 straightforward:</PARA>
623 <SCREEN>$ ecosconfig version v2_1 kernel</SCREEN>
624 <PARA>It is necessary to regenerate the build tree and header
625 files following any changes to the configuration before
626 rebuilding <productname>eCos</productname>:</PARA>
627 <SCREEN>$ ecosconfig tree</SCREEN>
629 <SECT1 id="fine-grained-configuration">
630 <TITLE>Fine-grained Configuration</TITLE>
631 <PARA><COMMAND>ecosconfig</COMMAND> only provides
632 coarse-grained control over the configuration: the hardware,
633 the template and the packages that should be built. Unlike
634 the Configuration Tool,
635 <COMMAND>ecosconfig</COMMAND> does not provide
636 any facilities for manipulating finer-grained <!--
637 <index></index> -->configuration options such as how many
638 priority levels the scheduler should support. There are
639 hundreds of these options, and manipulating them by means of
640 command line arguments would not be sensible. </PARA>
641 <PARA>In the current system fine-grained configuration options may
642 be manipulated by manual editing of the configuration file. When
643 a file has been edited in this way, the <COMMAND>ecosconfig</COMMAND> tool
644 should be used to check the configuration for any conflicts which
645 may have been introduced:</PARA>
646 <SCREEN>$ ecosconfig check</SCREEN>
647 <PARA>The <COMMAND>check</COMMAND> command will list
648 all conflicts and will also rewrite the configuration file, propagating
649 any changes which affect other options. The user may choose to resolve
650 the conflicts either by re-editing the configuration file manually
651 or by invoking the inference engine using the <COMMAND>resolve</COMMAND> command:</PARA>
652 <SCREEN>$ ecosconfig resolve</SCREEN>
653 <PARA>The <COMMAND>resolve</COMMAND> command will
654 list all conflicts which can be resolved and save the resulting changes
655 to the configuration.</PARA>
656 <PARA>It is necessary to regenerate the build tree and header files
657 following any changes to the configuration before rebuilding <productname>eCos</productname>:</PARA>
658 <SCREEN>$ ecosconfig tree</SCREEN>
659 <PARA>All the configuration options and their descriptions are listed
660 in the <citetitle><productname>eCos</productname> Reference Manual</citetitle>. </PARA>
662 <SECT1 id="editing-an-ecos-savefile">
663 <TITLE>Editing an <productname>eCos</productname> Savefile</TITLE>
664 <PARA>The <productname>eCos</productname> configuration information is held in a single
665 savefile, typically <FILENAME>ecos.ecc</FILENAME>, which can
666 be generated by either the GUI configuration tool or by the
667 command line <command>ecosconfig</command> tool. The file
668 normally exists at the top level of the build tree. It is a
669 text file, allowing the various configurations options to be
670 edited inside a suitable text editor or by other programs or
671 scripts, as well as in the GUI config tool.</PARA>
672 <PARA>An <productname>eCos</productname> savefile is actually a script in the <EMPHASIS>Tcl</EMPHASIS> programming
673 language, so any modifications to the file need to preserve Tcl
674 syntax. For most configuration options, any modifications will be
675 trivial and there is no need to worry about Tcl syntax. For example,
676 changing a 1 to a 0 to disable an option. For more complicated
677 options, for example<literal> CYGDAT_UITRON_TASK_EXTERNS</literal>,
678 which involves some lines of C code, more care has
679 to be taken. If an edited savefile is no longer a valid Tcl script
680 then the configuration tools will be unable to read back the data
681 for further processing, for example to generate a build tree. An
682 outline of Tcl syntax is given below. One point worth noting here
683 is that a line that begins with a “#” is
684 usually a comment, and the bulk of an <productname>eCos</productname> savefile actually consists
685 of such comments, to make it easier to edit.</PARA>
687 <TITLE>Header</TITLE>
688 <PARA>An <productname>eCos</productname> savefile begins with a header, which typically
689 looks something like this:</PARA>
690 <SCREEN># eCos saved configuration
691 # ---- commands --------------------------------------------------------
692 # This section contains information about the savefile format.
693 # It should not be edited. Any modifications made to this section
694 # may make it impossible for the configuration tools to read
697 cdl_savefile_version 1;
698 cdl_savefile_command cdl_savefile_version {};
699 cdl_savefile_command cdl_savefile_command {};
701 cdl_configuration { description hardware template package };
702 cdl_savefile_command cdl_package { value_source user_value wizard_value inferred_value };
703 cdl_savefile_command cdl_component { value_source user_value wizard_value inferred_value };
704 cdl_savefile_command cdl_option { value_source user_value wizard_value inferred_value };
705 cdl_savefile_command cdl_interface { value_source user_value wizard_value inferred_value };
707 <PARA>This section of the savefile is intended for use by the
708 configuration system, and should not be edited. If this
709 section is edited then the various configuration tools may no
710 longer be able to read in the modified savefile.</PARA>
713 <TITLE>Toplevel Section</TITLE>
714 <PARA>The header is followed by a section that defines the
715 configuration as a whole. A typical example would
717 <SCREEN># ---- toplevel --------------------------------------------------------
718 # This section defines the toplevel configuration object. The only
719 # values that can be changed are the name of the configuration and
720 # the description field. It is not possible to modify the target,
721 # the template or the set of packages simply by editing the lines
722 # below because these changes have wide-ranging effects. Instead
723 # the appropriate tools should be used to make such modifications.
725 cdl_configuration eCos {
726 description ““ ;
728 # These fields should not be modified.
731 package -hardware CYGPKG_HAL_ARM current ;
732 package -hardware CYGPKG_HAL_ARM_PID current ;
733 package -hardware CYGPKG_IO_SERIAL current ;
734 package -template CYGPKG_HAL current ;
735 package -template CYGPKG_IO current ;
736 package -template CYGPKG_INFRA current ;
737 package -template CYGPKG_KERNEL current ;
738 package -template CYGPKG_UITRON current ;
739 package -template CYGPKG_LIBC current ;
740 package -template CYGPKG_LIBM current ;
741 package -template CYGPKG_DEVICES_WALLCLOCK current ;
742 package -template CYGPKG_ERROR current ;
745 <PARA>This section allows the configuration tools to reload the
746 various packages that make up the configuration. Most of the information
747 should not be edited. If it is necessary to add a new package or
748 to remove an existing one then the appropriate tools should be used
749 for this, for example:</PARA>
750 <PROGRAMLISTING>$ ecosconfig remove CYGPKG_LIBM</PROGRAMLISTING>
751 <PARA>There are two fields which can be edited. Configurations have
752 a name; in this case <productname>eCos</productname>. They can also have a description, which
753 is some arbitrary text. The configuration tools do not make use
754 of these fields, they exist so that users can store additional information
755 about a configuration.</PARA>
758 <TITLE>Conflicts Section</TITLE>
759 <PARA>The toplevel section is followed by details of all the
760 conflicts (if any) in the configuration, for
762 <SCREEN># ---- conflicts -------------------------------------------------------
763 # There are 2 conflicts.
765 # option CYGNUM_LIBC_TIME_DST_DEFAULT_OFFSET
766 # Property LegalValues
767 # Illegal current value 100000
768 # Legal values are: -90000 to 90000
770 # option CYGSEM_LIBC_TIME_CLOCK_WORKING
772 # Requires constraint not satisfied: CYGFUN_KERNEL_THREADS_TIMER
774 <PARA>When editing a configuration you may end up with something
775 that is invalid. Any problems in the configuration will be reported
776 in the conflicts section. In this case there are two conflicts.
777 The option <literal>CYGNUM_LIBC_TIME_DST_DEFAULT_OFFSET</literal> has
778 been given an illegal value: typically this would be fixed by searching
779 for the definition of that option later on in the savefile and modifying
780 the value. The second conflict is more interesting, an unsatisfied <EMPHASIS>requires</EMPHASIS> constraint.
781 Configuration options are not independent: disabling some functionality
782 in, say, the kernel, can have an impact elsewhere; in this case
783 the C library. The various dependencies between the options are
784 specified by the component developers and checked by the configuration
785 system. In this case there are two obvious ways in which the conflict could
786 be resolved: re-enabling <literal>CYGFUN_KERNEL_THREADS_TIMER</literal>,
787 or disabling <literal>CYGSEM_LIBC_TIME_CLOCK_WORKING</literal>.
788 Both of these options will be listed later on in the file.</PARA>
789 <PARA>Some care has to be taken when modifying configuration options,
790 to avoid introducing new conflict. For instance it is possible that
791 there might be other options in the system which have a dependency
792 on <literal>CYGSEM_LIBC_TIME_CLOCK_WORKING</literal>,
793 so disabling that option may not be the best way to resolve the
794 conflict. Details of all such dependencies are provided in the appropriate
795 places in the savefile.</PARA>
796 <PARA>It is not absolutely required that a configuration be conflict-free
797 before generating a build tree and building <productname>eCos</productname>. It is up to the
798 developers of each component to decide what would happen if an attempt
799 is made to build <productname>eCos</productname> while there are still conflicts. In serious
800 cases there is likely to be a compile-time failure, or possibly
801 a link-time failure. In less serious cases the system may build
802 happily and the application can be linked with the resulting library,
803 but the component may not quite function as intended - although
804 it may still be good enough for the specific needs of the application.
805 It is also possible that everything builds and links, but once in
806 a while the system will unaccountably crash. Using a configuration
807 that still has conflicts is done entirely at the user’s
811 <TITLE>Data Section</TITLE>
812 <PARA>The bulk of the savefile lists the various packages,
813 components, and options, including their values and the
814 various dependencies. A number of global options come
815 first, especially those related to the build process such
816 as compiler flags. These are followed by the various
817 packages, and the components and options within those
818 packages, in order.</PARA>
819 <PARA>Packages, components and options are organized in a
820 hierarchy. If a particular component is disabled then all
821 options and sub-components below it will be inactive: any
822 changes made to these will have no effect. The savefile
823 contains information about the hierarchy in the form of
824 comments, for example:</PARA>
825 <SCREEN>cdl_package CYGPKG_KERNEL ...
827 cdl_component CYGPKG_KERNEL_EXCEPTIONS ...
829 cdl_option CYGSEM_KERNEL_EXCEPTIONS_DECODE ...
830 cdl_option CYGSEM_KERNEL_EXCEPTIONS_GLOBAL ...
832 cdl_component CYGPKG_KERNEL_SCHED ...
834 cdl_option CYGSEM_KERNEL_SCHED_MLQUEUE ...
835 cdl_option CYGSEM_KERNEL_SCHED_BITMAP ...
839 <PARA>This corresponds to the following hierarchy:</PARA>
840 <SCREEN> CYGPKG_KERNEL
841 CYGPKG_KERNEL_EXCEPTIONS
842 CYGSEM_KERNEL_EXCEPTIONS_DECODE
843 CYGSEM_KERNEL_EXCEPTIONS_GLOBAL
845 CYGSEM_KERNEL_SCHED_MLQUEUE
846 CYGSEM_KERNEL_SCHED_BITMAP
848 <PARA>Providing the hierarchy information in this way allows
849 programs or scripts to analyze the savefile and readily
850 determine the hierarchy. It could also be used by a
851 sufficiently powerful editor to support structured editing
852 of <productname>eCos</productname> savefiles. The information is not used by the
853 configuration tools themselves since they obtain the
854 hierarchy from the original CDL scripts.</PARA>
855 <PARA>Each configurable entity is preceded by a comment, of
856 the following form:</PARA>
857 <SCREEN># Kernel schedulers
858 # doc: ref/ecos-ref/ecos-kernel-overview.html#THE-SCHEDULER
859 # The eCos kernel provides a choice of schedulers. In addition
860 # there are a number of configuration options to control the
861 # detailed behaviour of these schedulers.
862 cdl_component CYGPKG_KERNEL_SCHED {
866 <PARA>This provides a short textual alias
867 <literal>Kernel schedulers</literal> for the
868 component. If online documentation is available for the
869 configurable entity then this will come next. Finally
870 there is a short description of the entity as a whole. All
871 this information is provided by the component
873 <PARA>Each configurable entity takes the form:</PARA>
874 <SCREEN><type> <name> {
877 <PARA>Configurable entities may not be active. This can be either
878 because the parent is disabled or inactive, or because there are
879 one or more <EMPHASIS>active_if</EMPHASIS> properties. Modifying
880 the value of an inactive entity has no effect on the configuration,
881 so this information is provided first:</PARA>
883 <SCREEN>cdl_option CYGSEM_KERNEL_EXCEPTIONS_DECODE {
884 # This option is not active
885 # The parent CYGPKG_KERNEL_EXCEPTIONS is disabled
891 cdl_option CYGIMP_IDLE_THREAD_YIELD {
892 # This option is not active
893 # ActiveIf constraint: (CYGNUM_KERNEL_SCHED_PRIORITIES == 1)
894 # CYGNUM_KERNEL_SCHED_PRIORITIES == 32
900 <PARA>For <literal>CYGIMP_IDLE_THREAD_YIELD</literal> the
901 savefile lists the expression that must be satisfied if the option
902 is to be active, followed by the current value of all entities that
903 are referenced in the expression, and finally the result of evaluating
904 that expression.</PARA>
905 <PARA>Not all options are directly modifiable in the savefile. First,
906 the value of packages (which is the version of that package loaded
907 into the configuration) cannot be modified here.</PARA>
910 cdl_package CYGPKG_KERNEL {
911 # Packages cannot be added or removed, nor can their version be changed,
912 # simply by editing their value. Instead the appropriate configuration
913 # should be used to perform these actions.
918 <PARA>The version of a package can be changed using e.g.: </PARA>
919 <SCREEN>$ ecosconfig version 1.3 CYGPKG_KERNEL</SCREEN>
920 <PARA>Even though a package’s value cannot be modified
921 here, it is still important for the savefile to contain the details.
922 In particular packages may impose constraints on other configurable
923 entities and may be referenced by other configurable entities. Also
924 it would be difficult to understand or extract the configuration’s
925 hierarchy if the packages were not listed in the appropriate places
926 in the savefile.</PARA>
927 <PARA>Some components (or, conceivably, options) do not have any
928 associated data. Typically they serve only to introduce another
929 level in the hierarchy, which can be useful in the context of the
930 GUI configuration tool.</PARA>
933 cdl_component CYGPKG_HAL_COMMON_INTERRUPTS {
934 # There is no associated value.
938 <PARA>Other components or options have a calculated value. These
939 are not user-modifiable, but typically the value will depend on
940 other options which can be modified. Such calculated options can
941 be useful when controlling what gets built or what ends up in the
942 generated configuration header files. A calculated value may also
943 effect other parts of the configuration, for instance, via a <EMPHASIS>requires</EMPHASIS> constraint.</PARA>
947 # Calculated value: CYGSEM_LIBC_STDIO_WANT_BUFFERED_IO ? CYGNUM_LIBC_STDIO_BUFSIZE : 0
948 # CYGSEM_LIBC_STDIO_WANT_BUFFERED_IO == 1
949 # CYGNUM_LIBC_STDIO_BUFSIZE == 256
954 <PARA>A special type of calculated value is the <EMPHASIS>interface</EMPHASIS>.
955 The value of an interface is the number of active and enabled options
956 which <EMPHASIS>implement</EMPHASIS> that interface. Again the value
957 of an interface cannot be modified directly; only by modifying the
958 options which implement the interface. However, an interface can
959 be referenced by other parts of the configuration. </PARA>
960 <SCREEN>cdl_interface CYGINT_KERNEL_SCHEDULER {
961 # Implemented by CYGSEM_KERNEL_SCHED_MLQUEUE, active, enabled
962 # Implemented by CYGSEM_KERNEL_SCHED_BITMAP, active, disabled
963 # This value cannot be modified here.
965 # Requires: 1 == CYGINT_KERNEL_SCHEDULER
966 # CYGINT_KERNEL_SCHEDULER == 1
970 <SCREEN># The following properties are affected by this value
971 # interface CYGINT_KERNEL_SCHEDULER
972 # Requires: 1 == CYGINT_KERNEL_SCHEDULER
974 <PARA>If the configurable entity is modifiable then there will be
975 lines like the following:</PARA>
977 cdl_option CYGSEM_KERNEL_SCHED_MLQUEUE {
980 # No user value, uncomment the following line to provide one.
982 # value_source default
988 <PARA>Configurable entities can have one of four different flavors:
989 none, bool, data and booldata. Flavor none indicates that there
990 is no data associated with the entity, typically it just acts as
991 a placeholder in the overall hierarchy. Flavor bool is the most
992 common, it is a simple yes-or-no choice. Flavor data is for more
993 complicated configuration choices, for instance the size of an array
994 or the name of a device. Flavor booldata is a combination of bool
995 and data: the option can be enabled or disabled, and there is some
996 additional data associated with the option as well.</PARA>
997 <PARA>In the above example the user has not modified this particular
998 option, as indicated by the comment and by the commented-out <literal>user_value</literal> line.
999 To disable this option the file should be edited to:</PARA>
1002 cdl_option CYGSEM_KERNEL_SCHED_MLQUEUE {
1005 # No user value, uncomment the following line to provide one.
1007 # value_source default
1013 <PARA>The comment preceding the <literal>user_value
1014 0</literal> line can be removed if desired, otherwise it
1015 will be removed automatically the next time the file is read and
1016 updated by the configuration tools.</PARA>
1017 <PARA>Much the same process should be used for options with the
1018 data flavor, for example:</PARA>
1020 cdl_option CYGNUM_LIBC_TIME_DST_DEFAULT_OFFSET {
1022 # No user value, uncomment the following line to provide one.
1024 # value_source default
1025 # Default value: 3600
1026 # Legal values: -90000 to 90000
1030 <PARA>can be changed to:</PARA>
1033 cdl_option CYGNUM_LIBC_TIME_DST_DEFAULT_OFFSET {
1036 # value_source default
1037 # Default value: 3600
1038 # Legal values: -90000 to 90000 };
1041 <PARA>Note that the original text provides the default value in
1042 the <literal>user_value</literal> comment,
1043 on the assumption that the desired new value is likely to be similar
1044 to the default value. The <literal>value_source</literal> comment
1045 does not need to be updated, it will be fixed up if the savefile
1046 is fed back into the configuration system and regenerated.</PARA>
1047 <PARA>For options with the booldata flavor, the <literal>user_value</literal> line
1048 needs take two arguments. The first argument is for the boolean
1049 part, the second for the data part. For example:</PARA>
1051 cdl_component CYGNUM_LIBM_COMPATIBILITY {
1053 # No user value, uncomment the following line to provide one.
1054 # user_value 1 POSIX
1055 # value_source default
1056 # Default value: 1 POSIX
1057 # Legal values: “POSIX” “IEEE” “XOPEN” “SVID”
1062 <PARA>could be changed to:</PARA>
1064 cdl_component CYGNUM_LIBM_COMPATIBILITY {
1067 # value_source default
1068 # Default value: 1 POSIX
1069 # Legal values: “POSIX” “IEEE” “XOPEN” “SVID”
1074 <PARA>or alternatively, if the whole component should be disabled,
1077 cdl_component CYGNUM_LIBM_COMPATIBILITY {
1080 # value_source default
1081 # Default value: 1 POSIX
1082 # Legal values: “POSIX” “IEEE” “XOPEN” “SVID”
1087 <PARA>Some options take values that span multiple lines. An example
1091 cdl_option CYGDAT_UITRON_MEMPOOLVAR_INITIALIZERS {
1093 # No user value, uncomment the following line to provide one.
1095 # “CYG_UIT_MEMPOOLVAR( vpool1, 2000 ), \\
1096 # CYG_UIT_MEMPOOLVAR( vpool2, 2000 ), \\
1097 # CYG_UIT_MEMPOOLVAR( vpool3, 2000 ),”
1098 # value_source default
1100 # “CYG_UIT_MEMPOOLVAR( vpool1, 2000 ), \\
1101 # CYG_UIT_MEMPOOLVAR( vpool2, 2000 ), \\
1102 # CYG_UIT_MEMPOOLVAR( vpool3, 2000 ),”
1106 <PARA>Setting a user value for this option involves uncommenting
1107 and modifying all relevant lines, for example:</PARA>
1110 cdl_option CYGDAT_UITRON_MEMPOOLVAR_INITIALIZERS {
1113 “CYG_UIT_MEMPOOLVAR( vpool1, 4000 ), \\
1114 CYG_UIT_MEMPOOLVAR( vpool2, 4000 ),”
1115 # value_source default
1117 # “CYG_UIT_MEMPOOLVAR( vpool1, 2000 ), \\
1118 # CYG_UIT_MEMPOOLVAR( vpool2, 2000 ), \\
1119 # CYG_UIT_MEMPOOLVAR( vpool3, 2000 ),”
1123 <PARA>In such cases appropriate care has to be taken to preserve
1124 Tcl syntax, as discussed below.</PARA>
1125 <PARA>The configuration system has the ability to keep track of
1126 several different values for any given option. All options
1127 start off with a default value, in other words their value
1128 source is set to <literal>default</literal>. If a
1129 configuration involves conflicts and the configuration
1130 system’s inference engine is allowed to resolve these
1131 automatically then it may provide an
1132 <literal>inferred</literal> value instead, for
1136 cdl_option CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT {
1138 # No user value, uncomment the following line to provide one.
1140 # The inferred value should not be edited directly.
1142 # value_source inferred
1148 <PARA>Inferred values are calculated by the configuration system
1149 and should not be edited by the user. If the inferred value is not
1150 correct then a user value should be substituted instead:</PARA>
1153 cdl_option CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT {
1156 # The inferred value should not be edited directly.
1158 # value_source inferred
1162 <PARA>The inference engine will not override a user value with an
1163 inferred one. Making a change like this may well re-introduce a
1164 conflict, since the inferred value was only calculated to resolve
1165 a conflict. Another run of the inference engine may find a different
1166 and more acceptable way of resolving the conflict, but this is not guaranteed
1167 and it may be up to the user to examine the various dependencies
1168 and work out an acceptable solution.</PARA>
1169 <PARA>Inferred values are listed in the savefile because the exact
1170 inferred value may depend on the order in which changes were made
1171 and conflicts were resolved. If the inferred values were absent
1172 then it is possible that reloading a savefile would not exactly
1173 restore the configuration. Default values on the other hand are
1174 entirely deterministic so there is no actual need for the values
1175 to be listed in the savefile. However, the default value can be
1176 very useful information so it is provided in a comment.</PARA>
1177 <PARA>Occasionally the user will want to do some experimentation,
1178 and temporarily switch an option from a user value back to a default
1179 or inferred one to see what the effect would be. This could be achieved
1180 by simply commenting out the user value. For instance, if the current
1181 savefile contains:</PARA>
1183 cdl_option CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT {
1186 # The inferred value should not be edited directly.
1194 <PARA>then the inferred value could be restored by commenting out
1195 or removing the <literal>user_value</literal> line:</PARA>
1197 cdl_option CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT {
1200 # The inferred value should not be edited directly.
1208 <PARA>This is fine for simple values. However if the value is complicated
1209 then there is a problem: commenting out the <LITERAL>user_value</LITERAL> line
1210 or lines means that the user value becomes invisible to the configuration system,
1211 so if the savefile is loaded and then regenerated the information
1212 will be lost. An alternative approach is to keep the <LITERAL>user_value</LITERAL> but
1213 explicitly set the <LITERAL>value_source</LITERAL> line,
1217 cdl_option CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT {
1220 # The inferred value should not be edited directly.
1222 value_source inferred
1228 <PARA>In this case the configuration system will use the inferred
1229 value for the purposes of dependency analysis etc., even though
1230 a user value is present. To restore the user value the <LITERAL>value_source</LITERAL> line
1231 can be commented out again. If there is no explicit <LITERAL>value_source</LITERAL> then
1232 the configuration system will just use the highest priority one:
1233 the user value if it exists; otherwise the inferred value if it
1234 exists; otherwise the default value which always exists.</PARA>
1235 <PARA>The default value for an option can be a simple constant,
1236 or it can be an expression involving other options. In the latter
1237 case the expression will be listed, together with the values for
1238 all options referenced in the expression and the current result
1239 of evaluating that expression. This is for informational purposes
1240 only, the default value is always recalculated deterministically
1241 when loading in a savefile.</PARA>
1244 cdl_option CYGBLD_GLOBAL_COMMAND_PREFIX {
1246 # No user value, uncomment the following line to provide one.
1247 # user_value arm-elf
1248 # value_source default
1249 # Default value: CYGHWR_THUMB ? “thumb-elf” : “arm-elf”
1255 <PARA>For options with the data or booldata flavor, there are likely
1256 to be constraints on the possible values. If the value is supposed
1257 to be a number in a given range and a user value of “<LITERAL>hello
1258 world</LITERAL>” is provided instead then there
1259 are likely to be compile-time failures. Component developers can
1260 specify constraints on the legal values, and these will be listed
1261 in the savefile.</PARA>
1263 cdl_option X_TLOSS {
1265 # No user value, uncomment the following line to provide one.
1266 # user_value 1.41484755040569E+16
1267 # value_source default
1268 # Default value: 1.41484755040569E+16
1269 # Legal values: 1 to 1e308
1273 <SCREEN>cdl_component CYGNUM_LIBM_COMPATIBILITY {
1275 # No user value, uncomment the following line to provide one.
1276 # user_value 1 POSIX
1277 # value_source default
1278 # Default value: 1 POSIX
1279 # Legal values: “POSIX” “IEEE” “XOPEN” “SVID”
1284 <PARA>In some cases the legal values list may be an expression involving
1285 other options. If so then the current values of the referenced options
1286 will be listed, together with the result of evaluating the list
1287 expression, just as for default value expressions.</PARA>
1288 <PARA>If an illegal value is provided then this will result in a
1289 conflict, listed in the conflicts section of the savefile. For more
1290 complicated options a simple legal values list is not sufficient
1291 to allow the current value to be validated, and the configuration
1292 system will be unable to flag conflicts. This issue will be addressed in
1293 future releases of the configuration system.</PARA>
1294 <PARA>Following the value-related fields for a given option, any <EMPHASIS>requires</EMPHASIS> constraints belonging
1295 to this option will be listed. These constraints are only effective
1296 if the option is active and, for bool and booldata flavors, enabled.
1297 If some aspect of <productname>eCos</productname> functionality is inactive or disabled then
1298 it cannot impose any constraints on the rest of the system. As usual,
1299 the full expression will be listed followed by the current values
1300 of all options that are referenced and the result of evaluating
1301 the expression:</PARA>
1304 cdl_option CYGSEM_LIBC_TIME_TIME_WORKING {
1306 # Requires: CYGPKG_DEVICES_WALLCLOCK
1307 # CYGPKG_DEVICES_WALLCLOCK == current
1312 <PARA>When modifying the value of an option it is useful to know
1313 not only what constraints the option imposes on the rest of the
1314 system but also what other options in the system depend in some
1315 way on this one. The savefile provides this information:</PARA>
1316 <SCREEN>cdl_option CYGFUN_KERNEL_THREADS_TIMER {
1318 # The following properties are affected by this value
1319 # option CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT
1320 # Requires: CYGFUN_KERNEL_THREADS_TIMER
1321 # option CYGIMP_UITRON_STRICT_CONFORMANCE
1322 # Requires: CYGFUN_KERNEL_THREADS_TIMER
1323 # option CYGSEM_LIBC_TIME_CLOCK_WORKING
1324 # Requires: CYGFUN_KERNEL_THREADS_TIMER
1330 <TITLE>Tcl Syntax</TITLE>
1331 <PARA><productname>eCos</productname> savefiles are implemented as Tcl scripts, and are read
1332 in by running the data through a standard Tcl interpreter that has
1333 been extended with a small number of additional commands such as <LITERAL>cdl_option</LITERAL> and <LITERAL>cdl_configuration</LITERAL>.
1334 In many cases this is an implementation detail that can be safely
1335 ignored while editing a savefile: simply replacing a <LITERAL>1</LITERAL> with
1336 a <LITERAL>0</LITERAL> to disable some functionality
1337 is not going to affect whether or not the savefile is still a valid
1338 Tcl script and can be processed by a Tcl interpreter. However, there
1339 are more complicated cases where an understanding of Tcl syntax
1340 is at least desirable, for example:</PARA>
1343 cdl_option CYGDAT_UITRON_MEMPOOLVAR_EXTERNS {
1346 “static char vpool1\[ 2000 \], \\
1347 vpool2\[ 2000 \], \\
1348 vpool3\[ 2000 \];”
1349 # value_source default
1351 # “static char vpool1\[ 2000 \], \\
1352 # vpool2\[ 2000 \], \\
1353 # vpool3\[ 2000 \];”
1357 <PARA>The backslash at the end of the <LITERAL>user_value</LITERAL> line
1358 is processed by the Tcl interpreter as a line continuation character.
1359 The quote marks around the user data are also interpreted by the
1360 Tcl interpreter and serve to turn the entire data field into a single
1361 argument. The backslashes preceding the opening and closing square
1362 brackets prevent the Tcl interpreter from treating these characters
1363 specially, otherwise there would be an attempt at <EMPHASIS>command
1364 substitution</EMPHASIS> as described below. The double backslashes
1365 at the end of each line of the data will be turned into a single
1366 backslash by the Tcl interpreter, rather than escaping the newline
1367 character, so that the actual data seen by the configuration system
1371 static char vpool1[ 2000 ], \
1376 <PARA>This is of course the data that should end up in the µITRON
1377 configuration header file. The opening and closing braces surrounding
1378 the entire body of the option data are also significant and cause
1379 this body to be passed as a single argument to the <command>cdl_option</command> command.
1380 The closing semicolon is optional in this example, but provides
1381 a small amount of additional robustness if the savefile is edited
1382 such that it is no longer a valid Tcl script. If the data contained
1383 any <LITERAL>$</LITERAL> characters then
1384 these would have to be treated specially as well, via a backslash escape.</PARA>
1385 <PARA>In spite of what all the above might seem to suggest, Tcl
1386 is actually a very simple yet powerful scripting language: the syntax
1387 is defined by just eleven rules. On occasion this simplicity means
1388 that Tcl’s behaviour is subtly different from other languages,
1389 which can confuse newcomers.</PARA>
1390 <PARA>When the Tcl interpreter is passed some data such as <LITERAL>puts
1391 Hello</LITERAL>, it splits this data into a command and its
1392 arguments. The command will be terminated by a newline or by a semicolon,
1393 unless one of the quoting mechanisms is used. The command and each
1394 of its arguments are separated by white space. So in the following
1398 <PARA>will result in two separate commands being executed. The first
1399 command is <LITERAL>puts</LITERAL> and is passed a
1400 single argument, <LITERAL>Hello</LITERAL>. The second
1401 command is <LITERAL>set</LITERAL> and is passed two
1402 arguments, <LITERAL>x</LITERAL> and <LITERAL>42</LITERAL>.
1403 The intervening newline character serves to terminate the first
1404 command, and a semi-colon separator could be used instead: </PARA>
1405 <programlisting>puts Hello;set x 42</programlisting>
1406 <PARA>Any white space surrounding the semicolon is just ignored
1407 because it does not serve to separate arguments.</PARA>
1408 <PARA>Now consider the following:</PARA>
1409 <SCREEN>set x Hello world</SCREEN>
1410 <PARA>This is not valid Tcl. It is an attempt to invoke the <LITERAL>set</LITERAL> command
1411 with three arguments: <LITERAL>x</LITERAL>, <LITERAL>Hello</LITERAL>,
1412 and <LITERAL>world</LITERAL>. The <LITERAL>set</LITERAL> only
1413 takes two arguments, a variable name and a value, so it is necessary
1414 to combine the data into a single argument by quoting:</PARA>
1415 <PROGRAMLISTING>set x “Hello world”</PROGRAMLISTING>
1416 <PARA>When the Tcl interpreter encounters the first quote character
1417 it treats all subsequent data up to but not including the closing
1418 quote as part of the current argument. The quote marks are removed
1419 by the interpreter, so the second argument passed to the <LITERAL>set</LITERAL> command
1420 is just <LITERAL>Hello world</LITERAL> without the
1421 quote characters. This can be significant in the context of <productname>eCos</productname> savefiles.
1422 For instance, consider the following configuration option:</PARA>
1425 cdl_option CYGDAT_LIBC_STDIO_DEFAULT_CONSOLE {
1427 # No user value, uncomment the following line to provide one.
1428 # user_value “\”/dev/ttydiag\””
1429 # value_source default
1430 # Default value: “\”/dev/ttydiag\””
1434 <PARA>The desired value of the configuration option should be a
1435 valid C string, complete with quote characters. If the savefile
1436 was edited to: </PARA>
1439 cdl_option CYGDAT_LIBC_STDIO_DEFAULT_CONSOLE {
1441 user_value “/dev/ttydiag”
1442 # value_source default
1443 # Default value: “\”/dev/ttydiag\””
1447 <PARA>then the Tcl interpreter would remove the quote marks when
1448 the savefile is read back in, so the option’s value would
1449 not have any quote marks and would not be a valid C string. The
1450 configuration system is not yet able to perform the required validation
1451 so the following <LITERAL>#define</LITERAL> would
1452 be generated in the configuration header file:</PARA>
1453 <PROGRAMLISTING>#define CYGDAT_LIBC_STDIO_DEFAULT_CONSOLE /dev/ttydiag </PROGRAMLISTING>
1454 <PARA>This is likely to cause a compile-time failure when building
1455 <productname>eCos</productname>.</PARA>
1456 <PARA>A quoted argument continues until the closing quote character
1457 is encountered, which means that it can span multiple lines. This
1458 can also be encountered in <productname>eCos</productname> savefiles, for instance, in the <literal>CYGDAT_UITRON_MEMPOOLVAR_EXTERNS</literal> example
1459 mentioned earlier. Newline or semicolon characters do not terminate
1460 the current command in such cases.</PARA>
1461 <PARA>The Tcl interpreter supports much the same forms of backslash
1462 substitution as other common programming languages. Some backslash
1463 sequences such as <literal>\n</literal> will
1464 be replaced by the appropriate character. The sequence <literal>\\</literal> will
1465 be replaced by a single backslash. A backslash at the very end of
1466 a line will cause that backslash, the newline character, and any
1467 white space at the start of the next line to be replaced by a single
1468 space. Hence the following two Tcl commands are equivalent:</PARA>
1469 <PROGRAMLISTING>puts “Hello\nworld\n”
1473 “</PROGRAMLISTING>
1474 <PARA>In addition to quote and backslash characters, the Tcl interpreter
1475 treats square brackets, the <literal>$</literal> character,
1476 and braces specially. Square brackets are used for command substitution,
1478 <PROGRAMLISTING>puts “The answer is [expr 6 * 9]”</PROGRAMLISTING>
1479 <PARA>When the Tcl interpreter encounters the square brackets it
1480 will treat the contents as another command that should be executed
1481 first, and the result of executing that is used when continuing
1482 to process the script. In this case the Tcl interpreter will execute
1483 the command <literal>expr 6 * 9</literal>,
1484 yielding a result of 54, and then the Tcl interpreter will execute
1485 <literal>puts “The answer is 54”</literal>. It should be noted that
1486 the interpreter contains only one level of substitution: if the
1487 result of performing command substitution performs further special
1488 characters such as square brackets then these will not be treated
1490 <PARA>Command line substitution is very unlikely to prove useful
1491 in the context of an <productname>eCos</productname> savefile, but it is part of the Tcl language
1492 and hence cannot be easily suppressed while reading in a savefile.
1493 As a result care has to be taken when savefile data involves square
1494 brackets. Consider the following:</PARA>
1497 cdl_option CYGDAT_UITRON_MEMPOOLFIXED_EXTERNS {
1500 “static char fpool1[ 2000 ],
1501 fpool2[ 2000 ];”
1505 <PARA>The Tcl interpreter will interpret the square brackets as
1506 an attempt at command substitution and hence it will attempt to
1507 execute the command <literal>2000</literal> with no
1508 arguments. No such command is defined by the Tcl language or by
1509 the savefile-related extensions provided by the configuration system,
1510 so this will result in an error when an attempt is made to read
1511 back the savefile. Instead it is necessary to backslash-escape the
1512 square brackets and thus suppress command substitution:</PARA>
1515 cdl_option CYGDAT_UITRON_MEMPOOLFIXED_EXTERNS {
1518 “static char fpool1\[ 2000 \],
1519 fpool2\[ 2000 \];”
1521 }; </PROGRAMLISTING>
1522 <PARA>Similarly the <literal>$</literal> character
1523 is used in Tcl scripts to perform variable substitution:</PARA>
1524 <PROGRAMLISTING>set x [expr 6 * 9]
1525 puts “The answer is $x” </PROGRAMLISTING>
1526 <PARA>Variable substitution, like command substitution, is very
1527 unlikely to prove useful in the context of an <productname>eCos</productname> savefile. Should
1528 it be necessary to have a <literal>$</literal> character
1529 in configuration data then again a backslash escape needs to be
1531 <PROGRAMLISTING>cdl_option FOODAT_MONITOR_PROMPT {
1533 user_value “\$ “
1536 <PARA>Braces are used to collect a sequence of characters into a
1537 single argument, just like quotes. The difference is that variable,
1538 command and backslash substitution do not occur inside braces (with
1539 the sole exception of backslash substitution at the end of a line).
1540 So, for example, the <literal>CYGDAT_UITRON_MEMPOOL_EXTERNFIXED_EXTERNS</literal> value
1541 could be written as:</PARA>
1542 <PROGRAMLISTING>cdl_option CYGDAT_UITRON_MEMPOOLFIXED_EXTERNS {
1545 {static char fpool1[ 2000 ],
1549 <PARA>The configuration system does not use this when generating
1550 savefiles because for simple edits of a savefile by inexperienced
1551 users the use of brace characters is likely to be a little bit more
1552 confusing than the use of quotes.</PARA>
1553 <PARA>At this stage it is worth noting that the basic format of
1554 each configuration option in the savefile makes use of braces:</PARA>
1555 <PROGRAMLISTING>cdl_option <name> {
1558 <PARA>The configuration system extends the Tcl language with a small
1559 number of additional commands such as <LITERAL>cdl_option</LITERAL>.
1560 These commands take two arguments, a name and a body, where the
1561 body consists of all the text between the braces. First a check
1562 is made that the specified option is actually present in the configuration.
1563 Then the body is executed in a recursive invocation of the Tcl interpreter,
1564 this time with additional commands such as <LITERAL>user_value</LITERAL> and <LITERAL>value_source</LITERAL>.
1565 If, after editing, the braces are not correctly matched up then
1566 the savefile will no longer be a valid Tcl script and errors will
1567 be reported when the savefile is loaded again.</PARA>
1568 <PARA>Comments in Tcl scripts are introduced by a hash character <LITERAL>#</LITERAL>.
1569 However, a hash character only introduces a comment if it occurs
1570 where a command is expected. Consider the following:</PARA>
1571 <PROGRAMLISTING># This is a comment
1572 puts “Hello” # world </PROGRAMLISTING>
1573 <PARA>The first line is a valid comment, since the hash character
1574 occurs right at the start where a command name is expected. The
1575 second line does not contain a comment. Instead it is an attempt
1576 to invoke the <LITERAL>puts</LITERAL> command with
1577 three arguments: <LITERAL>Hello</LITERAL>, <LITERAL>#</LITERAL> and <LITERAL>world</LITERAL>.
1578 These are not valid arguments for the <LITERAL>puts</LITERAL> command
1579 so an error will be raised.</PARA>
1580 <PARA>If the second line was rewritten as:</PARA>
1581 <PROGRAMLISTING>puts “Hello”; # world</PROGRAMLISTING>
1582 <PARA>then this is a valid Tcl script. The semicolon identifies
1583 the end of the current command, so the hash character occurs at
1584 a point where the next command would start and hence it is interpreted
1585 as the start of a comment.</PARA>
1586 <PARA>This handling of comments can lead to subtle behaviour. Consider
1587 the following:</PARA>
1588 <PROGRAMLISTING>cdl_option WHATEVER {
1589 # This is a comment }
1593 <PARA>Consider the way the Tcl interpreter processes this. The command
1594 name and the first argument do not pose any special difficulties.
1595 The opening brace is interpreted as the start of the next argument,
1596 which continues until a closing brace is encountered. In this case
1597 the closing brace occurs on the second line, so the second argument
1598 passed to <LITERAL>cdl_option</LITERAL> is <literal>\n # This is a comment</LITERAL> . This second argument
1599 is processed in a recursive invocation of the Tcl interpreter and
1600 does not contain any commands, just a comment. Toplevel savefile
1601 processing then resumes, and the next command that is encountered
1602 is <LITERAL>user_value</LITERAL>. Since the
1603 relevant savefile code is not currently processing a configuration
1604 option this is an error. Later on the Tcl interpreter would encounter
1605 a closing brace by itself, which is also an error. Fortunately this
1606 sequence of events is very unlikely to occur when editing generated
1608 <PARA>This should be sufficient information about Tcl to allow for
1609 safe editing of <productname>eCos</productname> savefiles. Further information is available
1610 from a wide variety of sources, for example the book <EMPHASIS>Tcl
1611 and the Tk Toolkit </EMPHASIS>by John K Ousterhout.</PARA>
1614 <SECT1 id="editing-the-sources">
1615 <TITLE>Editing the Sources</TITLE>
1616 <PARA>For many users, controlling the packages and
1617 manipulating the available configuration options will be
1618 sufficient to create an embedded operating system that meets
1619 the application's requirements. However, since <productname>eCos</productname> is
1620 shipped entirely in source form, it is possible to go
1621 further when necessary: you can edit the <productname>eCos</productname> <!--
1622 <index></index> -->sources themselves. This requires some
1623 understanding of the way the <productname>eCos</productname> build system works.
1625 <PARA>The most obvious place to edit the source code is directly
1626 in the <!-- <index></index> -->component repository. For example, you could
1627 edit the file <filename>kernel/<replaceable>&Version;</replaceable>/src/sync/mutex.cxx</filename>
1628 to change the way kernel mutexes work, or possibly just to add some
1629 extra diagnostics or assertions. Once the file has been edited,
1630 it is possible to invoke <command>make</command> at
1631 the top level of the build tree and the target library will be rebuilt
1632 as required. A small optimization is possible: the build tree is
1633 largely a mirror of the component repository, so it too will contain
1634 a subdirectory <filename>kernel/<replaceable>&Version;</replaceable></filename>;
1635 if make is invoked in this directory
1636 then it will only check for changes to the kernel sources, which
1637 is a bit more efficient than checking for changes throughout the component
1639 <PARA>Editing a file in the component repository is fine if this
1640 tree is used for only one <productname>eCos</productname> configuration. If the repository
1641 is used for several different configurations, however, and especially
1642 if it is shared by multiple users, then making what may be experimental
1643 changes to the master sources would be a bad idea. The build system provides
1644 an alternative. It is possible to make a copy of the file in the
1645 build tree, in other words copy <filename>mutex.cxx</filename> from
1646 the <filename>kernel/<replaceable>&Version;</replaceable>/src/sync</filename> directory
1647 in the component repository to <filename>kernel/<replaceable>&Version;</replaceable>/src/sync</filename> in
1648 the build tree, and edit the file in the build tree. When <command>make</command> is
1649 invoked it will pick up local copies of any of the sources in preference
1650 to the master versions in the component repository. Once you have
1651 finished modifying the <productname>eCos</productname> sources you can install the final version
1652 back in the component repository. If the changes were temporary
1653 in nature and only served to aid the debugging process, then you
1654 can discard the modified version of the sources. </PARA>
1655 <PARA>The situation is slightly more complicated for the header
1656 files that a package may export, such as the C library’s <filename>stdio.h</filename> header
1657 file, which can be found in the directory <filename>language/c/libc/<replaceable>&Version;</replaceable>/include</filename>.
1658 If such a header file is changed, either directly in the component
1659 repository or after copying it to the build tree, then <command>make</command> must
1660 be invoked at the top level of the build tree. In cases like this
1661 it is not safe to rebuild just the C library because other packages
1662 may depend on the contents of <filename>stdio.h</filename>. </PARA>
1664 <SECT1 id="modifying-the-memory-layout">
1665 <TITLE>Modifying the Memory Layout</TITLE>
1666 <PARA>Each <productname>eCos</productname> platform package is supplied with linker script
1667 fragments which describe the location of memory regions on the evaluation
1668 board and the location of memory sections within these regions.
1669 The correct linker script fragment is selected and included in the
1670 <productname>eCos</productname> linker script <!-- <index></index> --><filename>target.ld</filename> when
1671 <productname>eCos</productname> is built.</PARA>
1672 <PARA>It is not necessary to <!-- <index></index> -->modify the default memory
1673 layouts in order to start development with <productname>eCos</productname>. However, it will
1674 be necessary to edit a linker script fragment when the memory map
1675 of the evaluation board is changed. For example, if additional memory
1676 is added, the linker must be notified that the new memory is available
1677 for use. As a minimum, this would involve modifying the length of
1678 the corresponding memory region. Where the available memory is non-contiguous,
1679 it may be necessary to declare a new memory region and reassign
1680 certain linker output sections to the new region.</PARA>
1681 <PARA>Linker script fragments and memory layout header files should
1682 be <!-- <index></index> -->edited within the <productname>eCos</productname> install tree. They are
1683 located at <filename>include/pkgconf/mlt_*.*</filename>.
1684 Where multiple start-up types are in use, it will be necessary to
1685 edit multiple linker script fragments and header files. The information
1686 provided in the header file and the corresponding linker script
1687 fragment must always match. A typical linker script fragment is
1689 <EXAMPLE><!-- <index></index> -->
1690 <TITLE><productname>eCos</productname> linker script fragment</TITLE>
1691 <PROGRAMLISTING>MEMORY
1693 rom : ORIGIN = 0x40000000, LENGTH = 0x80000
1694 ram : ORIGIN = 0x48000000, LENGTH = 0x200000
1700 SECTION_rom_vectors (rom, 0x40000000, LMA_EQ_VMA)
1701 SECTION_text (rom, ALIGN (0x1), LMA_EQ_VMA)
1702 SECTION_fini (rom, ALIGN (0x1), LMA_EQ_VMA)
1703 SECTION_rodata (rom, ALIGN (0x1), LMA_EQ_VMA)
1704 SECTION_rodata1 (rom, ALIGN (0x1), LMA_EQ_VMA)
1705 SECTION_fixup (rom, ALIGN (0x1), LMA_EQ_VMA)
1706 SECTION_gcc_except_table (rom, ALIGN (0x1), LMA_EQ_VMA)
1707 SECTION_data (ram, 0x48000000, FOLLOWING (.gcc_except_table))
1708 SECTION_bss (ram, ALIGN (0x4), LMA_EQ_VMA)
1712 <PARA>The file consists of two blocks, the <literal>MEMORY</literal> block
1713 contains lines describing the address (<literal>ORIGIN</literal>)
1714 and the size (<literal>LENGTH</literal>) of each memory
1715 region. The <literal>MEMORY</literal> block is followed
1716 by the <literal>SECTIONS</literal> block which contains
1717 lines describing each of the linker output sections. Each section
1718 is represented by a macro call. The arguments of these macros are
1719 ordered as follows: </PARA>
1722 <PARA>The memory region in which the section will finally
1726 <PARA>The final address (
1727 <LITERAL>VMA</LITERAL>
1728 ) of the section. This is expressed using one of the following forms:</PARA>
1731 <TERM><EMPHASIS>n</EMPHASIS></TERM>
1733 <PARA>at the absolute address specified by the
1734 unsigned integer <EMPHASIS>n</EMPHASIS></PARA>
1738 <TERM>ALIGN (<EMPHASIS>n</EMPHASIS>)</TERM>
1740 <PARA>following the final location of the previous section
1741 with alignment to the next <EMPHASIS>n</EMPHASIS>-byte
1748 <PARA>The initial address (<LITERAL>LMA</LITERAL>)
1749 of the section. This is expressed using one of the
1750 following forms:</PARA>
1753 <TERM>LMA_EQ_VMA</TERM>
1755 <PARA>the <LITERAL>LMA</LITERAL>
1756 equals the <LITERAL>VMA</LITERAL> (no relocation)</PARA>
1760 <TERM>AT (<EMPHASIS>n</EMPHASIS>)</TERM>
1762 <PARA>at the absolute address specified by the
1763 unsigned integer <EMPHASIS>n</EMPHASIS></PARA>
1767 <TERM>FOLLOWING (.<EMPHASIS>name</EMPHASIS>)</TERM>
1769 <PARA>following the initial location of section
1770 <EMPHASIS>name</EMPHASIS></PARA>
1776 <PARA>In order to maintain compatibility with linker script
1777 fragments and header files exported by the
1778 <productname>eCos</productname> <APPLICATION>Configuration Tool</APPLICATION>, the use
1779 of other expressions within these files is not
1781 <PARA>Note that the names of the linker output sections will vary
1782 between target architectures. A description of these sections can
1783 be found in the specific <productname>GCC</productname> documentation for
1784 your architecture.</PARA>
1787 <CHAPTER id="managing-package-repository">
1788 <TITLE>Managing the <!-- <index></index> -->Package Repository</TITLE>
1789 <PARA>A source distribution of <productname>eCos</productname> consists of a number of
1790 packages, such as the kernel, the C library, and the
1791 µITRON subsystems. These are
1792 individually versioned in the tree structure of the source
1793 code, to support distribution on a per-package basis and to
1794 support third party packages whose versioning systems might be
1795 different. The <productname>eCos</productname> <application>Package
1796 Administration Tool</application> is used to manage the
1797 installation and removal of packages from a variety of sources
1798 with potentially multiple versions.</PARA>
1799 <PARA>The presence of the version information in the source tree
1800 structure might be a hindrance to the use of a separate source
1801 control system such as <EMPHASIS>CVS</EMPHASIS> or
1802 <EMPHASIS>SourceSafe</EMPHASIS>. To work
1803 in this way, you can rename all the version components to some
1804 common name (such as “current”) thus unifying the
1805 structure of source trees from distinct <productname>eCos</productname> releases.</PARA>
1806 <PARA>The <productname>eCos</productname> build system will treat any such name as just another
1807 version of the package(s), and support building in exactly the same
1808 way. However, performing this rename invalidates any existing build
1809 trees that referred to the versioned source tree, so do the rename
1810 first, before any other work, and do a complete rebuild afterwards.</PARA>
1811 <SECT1 id="package-installation">
1812 <TITLE>Package Installation</TITLE>
1813 <PARA>Package installation and removal is performed using the
1814 <productname>eCos</productname> <application>Package Administration Tool</application>. This
1815 tool is a Tcl script named
1816 <command>ecosadmin.tcl</command> which allows
1817 the user to add new <productname>eCos</productname> packages and new versions of
1818 existing packages to an <productname>eCos</productname> repository. Such packages must
1819 be distributed as a single file in the <productname>eCos</productname> package
1820 distribution format. Unwanted packages may also be removed
1821 from the repository using this tool. A graphical version of
1822 the tool is provided as part of the
1823 <productname>eCos</productname> <application>Configuration Tool</application>.</PARA>
1825 <TITLE>Using the Administration Tool</TITLE> <PARA>The graphical
1826 version of the <productname>eCos</productname> <application>Package
1827 Administration Tool</application>, provided as part of the
1828 <productname>eCos</productname> <application>Configuration
1829 Tool</application>, provides functions equivalent to the command-line
1830 version for those who prefer a Windows-based interface.</PARA>
1831 <PARA>It may be invoked in one of two ways:</PARA>
1834 <PARA>from the <GUIMENU>start menu</GUIMENU> (by default
1835 <GUIMENUITEM>Start->Programs->
1836 eCos->Package Administration
1837 Tool</GUIMENUITEM>)</PARA>
1840 XXXXX What is the Windows menu structure now? XXXXX
1846 <PARA>from the <productname>eCos</productname> <APPLICATION>Configuration
1847 Tool</APPLICATION> via the
1848 <GUIMENUITEM>Tools->Administration</GUIMENUITEM>
1852 <PARA><GRAPHIC ENTITYREF="graphic31"></GRAPHIC></PARA>
1853 <PARA>The main window of the tool displays the packages which are
1854 currently installed in the form of a tree. The installed versions
1855 of each package may be examined by expanding the tree.</PARA>
1856 <PARA>Packages may be added to the <productname>eCos</productname> repository by clicking on
1857 the <EMPHASIS>Add</EMPHASIS> button. The <productname>eCos</productname> package distribution
1858 file to be added is then selected via a <EMPHASIS>File Open</EMPHASIS> dialog
1860 <PARA>Packages may be removed by selecting a package in the tree
1861 and then clicking on the <EMPHASIS>Remove</EMPHASIS> button. If
1862 a package node is selected, all versions of the selected package
1863 will be removed. If a package version node is selected, only the
1864 selected version of the package will be removed.</PARA>
1867 <TITLE>Using the command line</TITLE>
1868 <PARA>The <command>ecosadmin.tcl</command>
1869 script is located in the base of the <productname>eCos</productname> repository. Use
1870 a command of the following form under versions of
1872 <SCREEN>$ tclsh ecosadmin.tcl <command></SCREEN>
1873 <PARA>Under Windows, a command of the following form may be used
1874 at the Cygwin command line prompt:</PARA>
1875 <SCREEN>$ cygtclsh80 ecosadmin.tcl <command></SCREEN>
1876 <PARA>The following commands are available:</PARA>
1879 <TERM><COMMAND>add <file></COMMAND></TERM>
1880 <LISTITEM><!-- <index></index> -->
1881 <PARA>Adds the packages contained with the specified package distribution
1882 file to the <productname>eCos</productname> repository and updates the package database accordingly.
1883 By convention, <productname>eCos</productname> package distribution files are given the <filename>.epk</filename> suffix.</PARA>
1887 <TERM><COMMAND>remove <package> [ --version=<version> ]</COMMAND></TERM><!-- <index></index> -->
1889 <PARA>Removes the specified package from the <productname>eCos</productname>
1890 repository and updates the package database
1891 accordingly. Where the optional version qualifier is
1892 used, only the specified version of the package is
1897 <TERM><COMMAND>list</COMMAND></TERM><!-- <index></index> -->
1899 <PARA>Produces a list of the packages which
1900 are currently installed and their versions. The
1901 available templates and hardware targets are also
1906 <PARA>Note that is is possible to remove critical packages
1907 such as the common HAL package using this tool. Users
1908 should take care to avoid such errors since core <productname>eCos</productname>
1909 packages may only be re-installed in the context of a
1910 complete re-installation of <productname>eCos</productname>.</PARA>
1913 <SECT1 id="package-structure">
1914 <TITLE>Package Structure</TITLE>
1915 <PARA>The files in an installed <productname>eCos</productname> source tree are organized in
1916 a natural tree structure, grouping together files which work together
1917 into <EMPHASIS>Packages</EMPHASIS>. For example, the kernel files
1918 are all together in: </PARA>
1920 <MEMBER><FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/kernel/<replaceable>&Version;</replaceable>/include/</FILENAME></MEMBER>
1921 <MEMBER> <FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/kernel/<replaceable>&Version;</replaceable>/src/</FILENAME></MEMBER>
1922 <MEMBER> <FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/kernel/<replaceable>&Version;</replaceable>/tests/</FILENAME></MEMBER>
1924 <PARA>and µITRON compatibility layer files are in:
1927 <MEMBER> <FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/compat/uitron/<replaceable>&Version;</replaceable>/include/</FILENAME></MEMBER>
1928 <MEMBER> <FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/compat/uitron/<replaceable>&Version;</replaceable>/src/</FILENAME></MEMBER>
1929 <MEMBER> <FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/compat/uitron/<replaceable>&Version;</replaceable>/tests/</FILENAME></MEMBER>
1931 <PARA>The feature of these names which is of interest here is
1932 the <replaceable>&Version;</replaceable> near the end. It may seem odd to place a version number deep in the
1933 path, rather than having something like
1934 <FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/<replaceable>&Version;</replaceable>/...everything...</FILENAME>
1935 or leaving it up to you to choose a different
1936 install-place when a new release of the system arrives.
1938 <PARA>There is a rationale for this organization: as
1939 indicated, the kernel and the
1940 µITRON compatibility subsystem
1941 are examples of software packages. For the first few
1942 releases of <productname>eCos</productname>, all the packages will move along
1943 in step, i.e. Release 1.3.x will feature Version
1944 1.3.x of every package, and so forth. But in future,
1945 especially when third party packages become available, it is
1946 intended that the package be the unit of software
1947 distribution, so it will be possible to build a system from
1948 a selection of packages with different version numbers, and
1949 even differing versioning <EMPHASIS>schemes</EMPHASIS>. A
1950 Tcl script <command>ecosadmin.tcl</command> is
1951 provided in the <productname>eCos</productname> repository to manage the installation
1952 and removal of packages in this way.</PARA>
1953 <PARA>Many users will have their own source code control system,
1954 version control system or equivalent, and will want to use it with
1955 <productname>eCos</productname> sources. In that case, since a new release of <productname>eCos</productname> comes with
1956 different pathnames for all the source files, a bit of work is necessary
1957 to import a new release into your source repository. </PARA>
1958 <PARA>One way of handling the import is to rename all the version
1959 parts to some common name, for example “current”,
1960 and continue to work. “current” is suggested because <command>ecosconfig</command> recognizes
1961 it and places it first in any list of versions. In the future, we
1962 may provide a tool to help with this, or an option in the install
1963 wizard. Alternatively, in a POSIX shell environment (Linux or Cygwin
1964 on Windows) use the following command: </PARA>
1965 <SCREEN>find . -name <replaceable>&Version;</replaceable> -type d -printf 'mv %p %h/current\n' | sh</SCREEN>
1966 <PARA>Having carried out such a renaming operation, your
1967 source tree will now look like this: </PARA>
1968 <SCREEN><REPLACEABLE>BASE_DIR</REPLACEABLE>/kernel/current/include/
1969 <REPLACEABLE>BASE_DIR</REPLACEABLE>/kernel/current/src/
1970 <REPLACEABLE>BASE_DIR</REPLACEABLE>/kernel/current/tests/
1972 <REPLACEABLE>BASE_DIR</REPLACEABLE>/compat/uitron/current/include/
1973 <REPLACEABLE>BASE_DIR</REPLACEABLE>/compat/uitron/current/src/
1974 <REPLACEABLE>BASE_DIR</REPLACEABLE>/compat/uitron/current/tests/
1976 <PARA>which is a suitable format for import into your own
1977 source code control system. When you get a subsequent
1978 release of <productname>eCos</productname>, do the same thing and use your own source
1979 code control system to manage the new source base, by
1980 importing the new version from </PARA>
1981 <SCREEN><REPLACEABLE>NEW_BASE_DIR</REPLACEABLE>/kernel/current/include/</SCREEN>
1982 <PARA>and so on. </PARA>
1983 <PARA>The <productname>eCos</productname> build tool will now offer only the
1984 “current” version of each package; select this
1985 for the packages you wish to use. </PARA>
1986 <PARA>Making such a change has implications for any build
1987 trees you already have in use. A configured build tree
1988 contains information about the selected packages and their
1989 selected versions. Changing the name of the
1990 “versioning” folder in the source tree
1991 invalidates this information, and in consequence it also
1992 invalidates any local configuration options you have set up
1993 in this build tree. So if you want to change the version
1994 information in the source tree, do it first, before
1995 investing any serious time in configuring and building your
1996 system. When you create a new build tree to deal with the
1997 new source layout, it will contain default settings for all
1998 the configuration options, just like the old build tree did
1999 before you configured it. You will need to redo that
2000 configuration work in the new tree. </PARA>
2001 <PARA>Moving source code around also invalidates debugging information
2002 in any programs or libraries built from the old tree; these will
2003 need to be rebuilt. </PARA>
2007 <!-- Keep this comment at the end of the file
2012 sgml-namecase-general:t
2013 sgml-general-insert-case:lower
2014 sgml-minimize-attributes:nil
2015 sgml-always-quote-attributes:t
2018 sgml-parent-document:("user-guide.sgml" "book" "part")
2019 sgml-exposed-tags:nil
2020 sgml-local-catalogs:nil
2021 sgml-local-ecat-files:nil
projects / karo-tx-redboot.git / blob