URL
https://opencores.org/ocsvn/openrisc_me/openrisc_me/trunk
Subversion Repositories openrisc_me
[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [cdl-guide/] [language.properties.html] - Rev 249
Go to most recent revision | Compare with Previous | Blame | View Log
<!-- Copyright (C) 2003 Red Hat, Inc. --> <!-- This material may be distributed only subject to the terms --> <!-- and conditions set forth in the Open Publication License, v1.0 --> <!-- or later (the latest version is presently available at --> <!-- http://www.opencontent.org/openpub/). --> <!-- Distribution of the work or derivative of the work in any --> <!-- standard (paper) book form is prohibited unless prior --> <!-- permission is obtained from the copyright holder. --> <HTML ><HEAD ><TITLE >CDL Properties</TITLE ><meta name="MSSmartTagsPreventParsing" content="TRUE"> <META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+ "><LINK REL="HOME" TITLE="The eCos Component Writer's Guide" HREF="cdl-guide.html"><LINK REL="UP" TITLE="The CDL Language" HREF="language.html"><LINK REL="PREVIOUS" TITLE="CDL Commands" HREF="language.commands.html"><LINK REL="NEXT" TITLE="Option Naming Convention" HREF="language.naming.html"></HEAD ><BODY CLASS="SECT1" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#840084" ALINK="#0000FF" ><DIV CLASS="NAVHEADER" ><TABLE SUMMARY="Header navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TH COLSPAN="3" ALIGN="center" >The <SPAN CLASS="APPLICATION" >eCos</SPAN > Component Writer's Guide</TH ></TR ><TR ><TD WIDTH="10%" ALIGN="left" VALIGN="bottom" ><A HREF="language.commands.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="80%" ALIGN="center" VALIGN="bottom" >Chapter 3. The CDL Language</TD ><TD WIDTH="10%" ALIGN="right" VALIGN="bottom" ><A HREF="language.naming.html" ACCESSKEY="N" >Next</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><DIV CLASS="SECT1" ><H1 CLASS="SECT1" ><A NAME="LANGUAGE.PROPERTIES">CDL Properties</H1 ><P >Each package, component, option, and interface has a body of properties, which provide the component framework with information about how to handle each option. For example there is a property for a descriptive text message which can be displayed to a user who is trying to figure out just what effect manipulating the option would have on the target application. There is another property for the default value, for example whether a particular option should be enabled or disabled by default.</P ><P >All of the properties are optional, it is legal to define a configuration option which has an empty body. However some properties are more optional than others: users will not appreciate having to manipulate an option if they are not given any sort of description or documentation. Other properties are intended only for very specific purposes, for example <SPAN CLASS="PROPERTY" >make_object</SPAN > and <SPAN CLASS="PROPERTY" >include_files</SPAN >, and are used only rarely.</P ><P >Because different properties serve very different purposes, their syntax is not as uniform as the top-level commands. Some properties take no arguments at all. Other properties take a single argument such as a description string, or a list of arguments such as a <SPAN CLASS="PROPERTY" >compile</SPAN > property which specifies the file or files that should be compiled if a given option is active and enabled. The <SPAN CLASS="PROPERTY" >define_proc</SPAN > property takes as argument a snippet of <SPAN CLASS="APPLICATION" >Tcl</SPAN > code. The <SPAN CLASS="PROPERTY" >active_if</SPAN >, <SPAN CLASS="PROPERTY" >calculated</SPAN >, <SPAN CLASS="PROPERTY" >default_value</SPAN >, <SPAN CLASS="PROPERTY" >legal_values</SPAN > and <SPAN CLASS="PROPERTY" >requires</SPAN > properties take various expressions. Additional properties may be defined in future which take new kinds of arguments.</P ><P >All property parsing code supports options for every property, although at present the majority of properties do not yet take any options. Any initial arguments that begin with a hyphen character <TT CLASS="LITERAL" >-</TT > will be interpreted as an option, for example:</P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >cdl_package CYGPKG_HAL_ARM { … make -priority 1 { … } }</PRE ></TD ></TR ></TABLE ><P >If the option involves additional data, as for the <TT CLASS="LITERAL" >-priority</TT > example above, then this can be written as either <TT CLASS="LITERAL" >-priority=1</TT > or as <TT CLASS="LITERAL" >-priority 1</TT >. On occasion the option parsing code can get in the way, for example:</P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >cdl_option CYGNUM_LIBC_TIME_DST_DEFAULT_STATE { … legal_values -1 to 1 default_value -1 }</PRE ></TD ></TR ></TABLE ><P >Neither the <SPAN CLASS="PROPERTY" >legal_values</SPAN > nor the <SPAN CLASS="PROPERTY" >default_value</SPAN > property will accept <TT CLASS="LITERAL" >-1</TT > as a valid option, so this will result in syntax errors when the <SPAN CLASS="APPLICATION" >CDL</SPAN > script is read in by the component framework. To avoid problems, the option parsing code will recognize the string <TT CLASS="LITERAL" >--</TT > and will not attempt to interpret any subsequent arguments. Hence this option should be written as:</P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >cdl_option CYGNUM_LIBC_TIME_DST_DEFAULT_STATE { … legal_values -- -1 to 1 default_value -- -1 }</PRE ></TD ></TR ></TABLE ><P >The property parsing code involves a recursive invocation of the Tcl interpreter that is used to parse the top-level commands. This means that some characters in the body of an option will be treated specially. The <TT CLASS="LITERAL" >#</TT > character can be used for comments. The backslash character <TT CLASS="LITERAL" >\</TT >, the dollar character <TT CLASS="LITERAL" >$</TT >, square brackets <TT CLASS="LITERAL" >[</TT > and <TT CLASS="LITERAL" >]</TT >, braces <TT CLASS="LITERAL" >{</TT > and <TT CLASS="LITERAL" >}</TT >, and the quote character <TT CLASS="LITERAL" >"</TT > may all receive special treatment. Most of the time this is not a problem because these characters are not useful for most properties. On occasion having a <SPAN CLASS="APPLICATION" >Tcl</SPAN > interpreter around performing the parser can be very powerful. For more details of how the presence of a <SPAN CLASS="APPLICATION" >Tcl</SPAN > interpreter can affect <SPAN CLASS="APPLICATION" >CDL</SPAN > scripts, see <A HREF="language.tcl.html" >the Section called <I >An Introduction to Tcl</I ></A >.</P ><P >Many of the properties can be used in any of <TT CLASS="LITERAL" >cdl_package</TT >, <TT CLASS="LITERAL" >cdl_component</TT >, <TT CLASS="LITERAL" >cdl_option</TT > or <TT CLASS="LITERAL" >cdl_interface</TT >. Other properties are more specific. The <SPAN CLASS="PROPERTY" >script</SPAN > property is only relevant to components. The <SPAN CLASS="PROPERTY" >define_header</SPAN >, <SPAN CLASS="PROPERTY" >hardware</SPAN >, <SPAN CLASS="PROPERTY" >include_dir</SPAN >, <SPAN CLASS="PROPERTY" >include_files</SPAN >, and <SPAN CLASS="PROPERTY" >library</SPAN > properties apply to a package as a whole, so can only occur in the body of a <TT CLASS="LITERAL" >cdl_package</TT > command. The <SPAN CLASS="PROPERTY" >calculated</SPAN >, <SPAN CLASS="PROPERTY" >default_value</SPAN >, <SPAN CLASS="PROPERTY" >legal_values</SPAN > and <SPAN CLASS="PROPERTY" >flavor</SPAN > properties are not relevant to packages, as will be explained later. The <SPAN CLASS="PROPERTY" >calculated</SPAN > and <SPAN CLASS="PROPERTY" >default_value</SPAN > properties are also not relevant to interfaces.</P ><P >This section lists the various properties, grouped by purpose. Each property also has a full reference page in <A HREF="reference.html" >Chapter 5</A >. Properties related to values and expressions are described in more detail in <A HREF="language.values.html" >the Section called <I >Values and Expressions</I ></A >. Properties related to header file generation and to the build process are described in <A HREF="build.html" >Chapter 4</A >.</P ><DIV CLASS="SECT2" ><H2 CLASS="SECT2" ><A NAME="LANGUAGE.PROPERTIES.USER">Information-providing Properties</H2 ><P >Users can only be expected to manipulate configuration options sensibly if they are given sufficient information about these options. There are three properties which serve to explain an option in plain text: the <A HREF="ref.display.html" ><SPAN CLASS="PROPERTY" >display</SPAN ></A > property gives a textual alias for an option, which is usually more comprehensible than something like <TT CLASS="LITERAL" >CYGPKG_LIBC_TIME_ZONES`</TT >; the <A HREF="ref.description.html" ><SPAN CLASS="PROPERTY" >description</SPAN ></A > property gives a longer description, typically a paragraph or so; the <A HREF="ref.doc.html" ><SPAN CLASS="PROPERTY" >doc</SPAN ></A > property specifies the location of additional on-line documentation related to a configuration option. In the context of a graphical tool the <SPAN CLASS="PROPERTY" >display</SPAN > string will be the primary way for users to identify configuration options; the <SPAN CLASS="PROPERTY" >description</SPAN > paragraph will be visible whenever the option is selected; the on-line documentation will only be accessed when the user explicitly requests it.</P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >cdl_package CYGPKG_UITRON { display "uITRON compatibility layer" doc ref/ecos-ref.a.html description " eCos supports a uITRON Compatibility Layer, providing full Level S (Standard) compliance with Version 3.02 of the uITRON Standard, plus many Level E (Extended) features. uITRON is the premier Japanese embedded RTOS standard." … }</PRE ></TD ></TR ></TABLE ><P >All three properties take a single argument. For <SPAN CLASS="PROPERTY" >display</SPAN > and <SPAN CLASS="PROPERTY" >description</SPAN > this argument is just a string. For <SPAN CLASS="PROPERTY" >doc</SPAN > it should be a pointer to a suitable HTML file, optionally including an anchor within that page. If the <A HREF="package.html#PACKAGE.HIERARCHY" >directory layout conventions</A > are observed then the component framework will look for the HTML file in the package's <TT CLASS="FILENAME" >doc</TT > sub-directory, otherwise the <SPAN CLASS="PROPERTY" >doc</SPAN > filename will be treated as relative to the package's top-level directory.</P ></DIV ><DIV CLASS="SECT2" ><H2 CLASS="SECT2" ><A NAME="LANGUAGE.PROPERTIES.HIERARCHY">The Configuration Hierarchy</H2 ><P >There are two properties related to the hierarchical organization of components and options: <A HREF="ref.parent.html" ><SPAN CLASS="PROPERTY" >parent</SPAN ></A > and <A HREF="ref.script.html" ><SPAN CLASS="PROPERTY" >script</SPAN ></A >.</P ><P >The <SPAN CLASS="PROPERTY" >parent</SPAN > property can be used to move a <SPAN CLASS="APPLICATION" >CDL</SPAN > entity somewhere else in the hierarchy. The most common use is for packages, to avoid having all the packages appear at the top-level of the configuration hierarchy. For example an architectural HAL package such as <TT CLASS="VARNAME" >CYGPKG_HAL_SH</TT > is placed below the common HAL package <TT CLASS="VARNAME" >CYGPKG_HAL</TT > using a <SPAN CLASS="PROPERTY" >parent</SPAN > property.</P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >cdl_package CYGPKG_HAL_SH { display "SH architecture" parent CYGPKG_HAL … }</PRE ></TD ></TR ></TABLE ><P >The <SPAN CLASS="PROPERTY" >parent</SPAN > property can also be used in the body of a <TT CLASS="LITERAL" >cdl_component</TT >, <TT CLASS="LITERAL" >cdl_option</TT > or <TT CLASS="LITERAL" >cdl_interface</TT >, but this is less common. However care has to be taken since excessive re-parenting can be confusing. Care also has to be taken when reparenting below some other package that may not actually be loaded in a given configuration, since the resulting behavior is undefined.</P ><P >As a special case, if the parent is the empty string then the <SPAN CLASS="APPLICATION" >CDL</SPAN > entity is placed at the root of the hierarchy. This is useful for global preferences, default compiler flags, and other settings that may affect every package.</P ><P >The <SPAN CLASS="PROPERTY" >script</SPAN > property can only be used in the body of a <TT CLASS="LITERAL" >cdl_component</TT > command. The property takes a single filename as argument, and this should be another <SPAN CLASS="APPLICATION" >CDL</SPAN > script containing additional options, sub-components and interfaces that should go below the current component in the hierarchy. If the <A HREF="package.html#PACKAGE.HIERARCHY" >directory layout conventions</A > are observed then the component framework will look for the specified file relative to the <TT CLASS="FILENAME" >cdl</TT > subdirectory of the package, otherwise the filename will be treated as relative to the package's top-level directory.</P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >cdl_component CYGPKG_LIBC_STDIO { display "Standard input/output functions" flavor bool requires CYGPKG_IO requires CYGPKG_IO_SERIAL_HALDIAG default_value 1 description " This enables support for standard I/O functions from <stdio.h>." script stdio.cdl }</PRE ></TD ></TR ></TABLE ></DIV ><DIV CLASS="SECT2" ><H2 CLASS="SECT2" ><A NAME="LANGUAGE.PROPERTIES.VALUE">Value-related Properties</H2 ><P >There are seven properties which are related to option values and state: <A HREF="ref.flavor.html" ><SPAN CLASS="PROPERTY" >flavor</SPAN ></A >, <A HREF="ref.calculated.html" ><SPAN CLASS="PROPERTY" >calculated</SPAN ></A >, <A HREF="ref.default-value.html" ><SPAN CLASS="PROPERTY" >default_value</SPAN ></A >, <A HREF="ref.legal-values.html" ><SPAN CLASS="PROPERTY" >legal_values</SPAN ></A >, <A HREF="ref.active-if.html" ><SPAN CLASS="PROPERTY" >active_if</SPAN ></A >, <A HREF="ref.implements.html" ><SPAN CLASS="PROPERTY" >implements</SPAN ></A >, and <A HREF="ref.requires.html" ><SPAN CLASS="PROPERTY" >requires</SPAN ></A >. More detailed information can be found in <A HREF="language.values.html" >the Section called <I >Values and Expressions</I ></A >.</P ><P >In the context of configurability, the concept of an option's value is somewhat non-trivial. First an option may or may not be loaded: it is possible to build a configuration which has the math library but not the kernel; however the math library's <SPAN CLASS="APPLICATION" >CDL</SPAN > scripts still reference kernel options, for example <TT CLASS="VARNAME" >CYGSEM_LIBM_THREAD_SAFE_COMPAT_MODE</TT > has a <SPAN CLASS="PROPERTY" >requires</SPAN > constraint on <TT CLASS="VARNAME" >CYGVAR_KERNEL_THREADS_DATA</TT >. Even if an option is loaded it may or may not be active, depending on what is happening higher up in the hierarchy: if the C library's <TT CLASS="VARNAME" >CYGPKG_LIBC_STDIO</TT > component is disabled then some other options such as <TT CLASS="VARNAME" >CYGNUM_LIBC_STDIO_BUFSIZE</TT > become irrelevant. In addition each option has both a boolean enabled/disabled flag and a data part. For many options only the boolean flag is of interest, while for others only the data part is of interest. The <SPAN CLASS="PROPERTY" >flavor</SPAN > property can be used to control this:</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT ><TT CLASS="LITERAL" >flavor none</TT ></DT ><DD ><P >This flavor indicates that neither the boolean nor the data parts are user-modifiable: the option is always enabled and the data is always set to <TT CLASS="LITERAL" >1</TT >. The most common use for this is to have a component that just acts as a placeholder in the hierarchy, allowing various options to be grouped below it.</P ></DD ><DT ><TT CLASS="LITERAL" >flavor bool</TT ></DT ><DD ><P >Only the boolean part of the option is user-modifiable. The data part is fixed at <TT CLASS="LITERAL" >1</TT >.</P ></DD ><DT ><TT CLASS="LITERAL" >flavor data</TT ></DT ><DD ><P >Only the data part of the option is user-modifiable. The boolean part is fixed at enabled.</P ></DD ><DT ><TT CLASS="LITERAL" >flavor booldata</TT ></DT ><DD ><P >Both the boolean and the data part of the option are user-modifiable.</P ></DD ></DL ></DIV ><P >For more details of <SPAN CLASS="APPLICATION" >CDL</SPAN > flavors and how a flavor affects expression evaluation, and other consequences, see <A HREF="language.values.html" >the Section called <I >Values and Expressions</I ></A >. The <SPAN CLASS="PROPERTY" >flavor</SPAN > property cannot be used for a package because packages always have the <TT CLASS="LITERAL" >booldata</TT > flavor. Options and components have the <TT CLASS="LITERAL" >bool</TT > flavor by default, since most configuration choices are simple yes-or-no choices. Interfaces have the <TT CLASS="LITERAL" >data</TT > flavor by default.</P ><P >The <SPAN CLASS="PROPERTY" >calculated</SPAN > property can be used for options which should not be user-modifiable, but which instead are fixed by the target hardware or determined from the current values of other options. In general <SPAN CLASS="PROPERTY" >calculated</SPAN > options should be avoided, since they can be confusing to users who need to figure out whether or not a particular option can actually be changed. There are a number of valid uses for <SPAN CLASS="PROPERTY" >calculated</SPAN > options, and quite a few invalid ones as well. The <A HREF="ref.calculated.html" >reference packages</A > should be consulted for further details. The property takes an <A HREF="language.values.html#LANGUAGE.EXPRESSION" >ordinary <SPAN CLASS="APPLICATION" >CDL</SPAN > expression</A > as argument, for example:</P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" ># A constant on some target hardware, perhaps user-modifiable on other # targets. cdl_option CYGNUM_HAL_RTC_PERIOD { display "Real-time clock period" flavor data calculated 12500 }</PRE ></TD ></TR ></TABLE ><P >The <SPAN CLASS="PROPERTY" >calculated</SPAN > property cannot be used for packages or interfaces. The value of a package always corresponds to the version of that package which is loaded, and this is under user control. Interfaces are implicitly calculated, based on the number of active and enabled implementors.</P ><P >The <SPAN CLASS="PROPERTY" >default_value</SPAN > property is similar to <SPAN CLASS="PROPERTY" >calculated</SPAN >, but only specifies a default value which users can modify. Again this property is not relevant to packages or interfaces. A typical example would be:</P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >cdl_option CYGDBG_HAL_DEBUG_GDB_THREAD_SUPPORT { display "Include GDB multi-threading debug support" requires CYGDBG_KERNEL_DEBUG_GDB_THREAD_SUPPORT default_value CYGDBG_KERNEL_DEBUG_GDB_THREAD_SUPPORT … }</PRE ></TD ></TR ></TABLE ><P >The <SPAN CLASS="PROPERTY" >legal_values</SPAN > property imposes a constraint on the possible values of the data part of an option. Hence it is only applicable to options with the <TT CLASS="LITERAL" >data</TT > or <TT CLASS="LITERAL" >booldata</TT > flavors. It cannot be used for a package since the only valid value for a package is its version number. The arguments to the <SPAN CLASS="PROPERTY" >legal_values</SPAN > property should constitute a <A HREF="language.values.html#LANGUAGE.LIST-EXPRESSION" ><SPAN CLASS="APPLICATION" >CDL</SPAN > list expression</A >.</P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >cdl_option CYGNUM_LIBC_TIME_STD_DEFAULT_OFFSET { display "Default Standard Time offset" flavor data legal_values -- -90000 to 90000 default_value -- 0 … }</PRE ></TD ></TR ></TABLE ><P >The <SPAN CLASS="PROPERTY" >active_if</SPAN > property does not relate directly to an option's value, but rather to its active state. Usually this is controlled via the configuration hierarchy: if the <TT CLASS="VARNAME" >CYGPKG_LIBC_STDIO</TT > component is disabled then all options below it are inactive and do not have any consequences. In some cases the hierarchy does not provide sufficient control, for example an option should only be active if two disjoint sets of conditions are satisfied: the hierarchy could be used for one of these conditions, and an additional <SPAN CLASS="PROPERTY" >active_if</SPAN > property could be used for the other one. The arguments to <SPAN CLASS="PROPERTY" >active_if</SPAN > should constitute a <A HREF="language.values.html#LANGUAGE.GOAL-EXPRESSION" ><SPAN CLASS="APPLICATION" >CDL</SPAN > goal expression</A >.</P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" ># Do not provide extra semaphore debugging if there are no semaphores cdl_option CYGDBG_KERNEL_INSTRUMENT_BINSEM { active_if CYGPKG_KERNEL_SYNCH … }</PRE ></TD ></TR ></TABLE ><P >The <SPAN CLASS="PROPERTY" >implements</SPAN > property is related to the concept of <A HREF="language.interface.html" ><SPAN CLASS="APPLICATION" >CDL</SPAN > interfaces</A >. If an option is active and enabled and it implements a particular interface then it contributes <TT CLASS="LITERAL" >1</TT > to that interface's value.</P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >cdl_package CYGPKG_NET_EDB7XXX_ETH_DRIVERS { display "Cirrus Logic ethernet driver" implements CYGHWR_NET_DRIVERS implements CYGHWR_NET_DRIVER_ETH0 … }</PRE ></TD ></TR ></TABLE ><P >The <SPAN CLASS="PROPERTY" >requires</SPAN > property is used to impose constraints on the user's choices. For example it is unreasonable to expect the C library to provide thread-safe implementations of certain functions if the underlying kernel support has been disabled, or even if the kernel is not being used at all.</P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >cdl_option CYGSEM_LIBC_PER_THREAD_ERRNO { display "Per-thread errno" doc ref/ecos-ref.15.html requires CYGVAR_KERNEL_THREADS_DATA default_value 1 … }</PRE ></TD ></TR ></TABLE ><P >The arguments to the <SPAN CLASS="PROPERTY" >requires</SPAN > property should be a <A HREF="language.values.html#LANGUAGE.GOAL-EXPRESSION" ><SPAN CLASS="APPLICATION" >CDL</SPAN > goal expression</A >.</P ></DIV ><DIV CLASS="SECT2" ><H2 CLASS="SECT2" ><A NAME="LANGUAGE.PROPERTIES.DEFINE">Generating the Configuration Header Files</H2 ><P >When creating or updating a build tree the component framework will also generate configuration header files, one per package. By default it will generate a <TT CLASS="LITERAL" >#define</TT > for each option, component or interface that is active and enabled. For options with the <TT CLASS="LITERAL" >data</TT > or <TT CLASS="LITERAL" >booldata</TT > flavors the <TT CLASS="LITERAL" >#define</TT > will use the option's data part, otherwise it will use the constant <TT CLASS="LITERAL" >1</TT >. Typical output would include:</P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >#define CYGFUN_LIBC_TIME_POSIX 1 #define CYGNUM_LIBC_TIME_DST_DEFAULT_STATE -1</PRE ></TD ></TR ></TABLE ><P >There are six properties which can be used to control the header file generation process: <A HREF="ref.define-header.html" ><SPAN CLASS="PROPERTY" >define_header</SPAN ></A >, <A HREF="ref.no-define.html" ><SPAN CLASS="PROPERTY" >no_define</SPAN ></A >, <A HREF="ref.define-format.html" ><SPAN CLASS="PROPERTY" >define_format</SPAN ></A >, <A HREF="ref.define.html" ><SPAN CLASS="PROPERTY" >define</SPAN ></A >, <A HREF="ref.if-define.html" ><SPAN CLASS="PROPERTY" >if_define</SPAN ></A >, and <A HREF="ref.define-proc.html" ><SPAN CLASS="PROPERTY" >define_proc</SPAN ></A >.</P ><P >By default the component framework will generate a configuration header file for each package based on the package's name: everything up to and including the first underscore is discarded, the rest of the name is lower-cased, and a <TT CLASS="LITERAL" >.h</TT > suffix is appended. For example the configuration header file for the kernel package <TT CLASS="VARNAME" >CYGPKG_KERNEL</TT > is <TT CLASS="FILENAME" >pkgconf/kernel.h</TT >. The <SPAN CLASS="PROPERTY" >define_header</SPAN > property can be used to specify an alternative filename. This applies to all the components and options within a package, so it can only be used in the body of a <TT CLASS="LITERAL" >cdl_package</TT > command. For example the following specifies that the configuration header file for the SPARClite HAL package is <TT CLASS="FILENAME" >pkgconf/hal_sparclite.h</TT >.</P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >cdl_package CYGPKG_HAL_SPARCLITE { display "SPARClite architecture" parent CYGPKG_HAL hardware define_header hal_sparclite.h … }</PRE ></TD ></TR ></TABLE ><DIV CLASS="NOTE" ><BLOCKQUOTE CLASS="NOTE" ><P ><B >Note: </B >At present the main use for the <SPAN CLASS="PROPERTY" >define_header</SPAN > property is related to hardware packages, see the <A HREF="ref.hardware.html" >reference pages</A > for more details.</P ></BLOCKQUOTE ></DIV ><P >The <SPAN CLASS="PROPERTY" >no_define</SPAN > property is used to suppress the generation of the default <TT CLASS="LITERAL" >#define</TT >. This can be useful if an option's consequences are all related to the build process or to constraints, and the option is never actually checked in any source code. It can also be useful in conjunction with the <SPAN CLASS="PROPERTY" >define</SPAN >, <SPAN CLASS="PROPERTY" >if_define</SPAN > or <SPAN CLASS="PROPERTY" >define_proc</SPAN > properties. The <SPAN CLASS="PROPERTY" >no_define</SPAN > property does not take any arguments. </P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >cdl_component CYG_HAL_STARTUP { display "Startup type" flavor data legal_values { "RAM" "ROM" } default_value {"RAM"} no_define define -file system.h CYG_HAL_STARTUP … }</PRE ></TD ></TR ></TABLE ><P >This example also illustrates the <SPAN CLASS="PROPERTY" >define</SPAN > property, which can be used to generate a <TT CLASS="LITERAL" >#define</TT > in addition to the default one. It takes a single argument, the name of the symbol to be defined. It also takes options to control the configuration header file in which the symbol should be defined and the format to be used.</P ><P >The <SPAN CLASS="PROPERTY" >define_format</SPAN > property can be used to control how the value part of the default <TT CLASS="LITERAL" >#define</TT > gets formatted. For example a format string of <TT CLASS="LITERAL" >"0x%04x"</TT > could be used to generate a four-digit hexadecimal number. </P ><P >The <SPAN CLASS="PROPERTY" >if_define</SPAN > property is intended for use primarily to control assertions, tracing, and similar functionality. It supports a specific implementation model for these, allowing control at the grain of packages or even individual source files. The <A HREF="ref.if-define.html" >reference pages</A > provide additional information.</P ><P >The <SPAN CLASS="PROPERTY" >define_proc</SPAN > property provides an escape mechanism for those cases where something special has to happen at configuration header file generation time. It takes a single argument, a fragment of <SPAN CLASS="APPLICATION" >Tcl</SPAN > code, which gets executed when the header file is generated. This code can output arbitrary data to the header file, or perform any other actions that might be appropriate.</P ></DIV ><DIV CLASS="SECT2" ><H2 CLASS="SECT2" ><A NAME="LANGUAGE.PROPERTIES.BUILD">Controlling what gets Built</H2 ><P >There are six properties which affect the build process: <A HREF="ref.compile.html" ><SPAN CLASS="PROPERTY" >compile</SPAN ></A >, <A HREF="ref.make.html" ><SPAN CLASS="PROPERTY" >make</SPAN ></A >, <A HREF="ref.make-object.html" ><SPAN CLASS="PROPERTY" >make_object</SPAN ></A >, <A HREF="ref.library.html" ><SPAN CLASS="PROPERTY" >library</SPAN ></A >, <A HREF="ref.include-dir.html" ><SPAN CLASS="PROPERTY" >include_dir</SPAN ></A >, and <A HREF="ref.include-files.html" ><SPAN CLASS="PROPERTY" >include_files</SPAN ></A >. The last three apply to a package as a whole, and can only occur in the body of a <TT CLASS="LITERAL" >cdl_package</TT > command.</P ><P >Most of the source files that go into a package should simply be compiled with the appropriate compiler, selected by the target architecture, and with the appropriate flags, with an additional set defined by the target hardware and possible modifications on a per-package basis. The resulting object files will go into the library <TT CLASS="FILENAME" >libtarget.a</TT >, which can then be linked against application code. The <SPAN CLASS="PROPERTY" >compile</SPAN > property is used to list these source files: </P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >cdl_package CYGPKG_ERROR { display "Common error code support" compile strerror.cxx include_dir cyg/error … }</PRE ></TD ></TR ></TABLE ><P >The arguments to the <SPAN CLASS="PROPERTY" >compile</SPAN > property should be one or more source files. Typically most of the sources will be needed for the package as a whole, and hence they will be listed in one or more <SPAN CLASS="PROPERTY" >compile</SPAN > properties in the body of the <TT CLASS="LITERAL" >cdl_package</TT >. Some sources may be specific to particular configuration options, in other words there is no point in compiling them unless that option is enabled, in which case the sources should be listed in a <SPAN CLASS="PROPERTY" >compile</SPAN > property in the corresponding <TT CLASS="LITERAL" >cdl_option</TT >, <TT CLASS="LITERAL" >cdl_component</TT > or <TT CLASS="LITERAL" >cdl_interface</TT > body.</P ><P >Some packages may have more complicated build requirements, for example they may involve a special target such as a linker script which should not end up in the usual library, or they may involve special build steps for generating an object file. The <SPAN CLASS="PROPERTY" >make</SPAN > and <SPAN CLASS="PROPERTY" >make_object</SPAN > properties provide support for such requirements, for example:</P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >cdl_package CYGPKG_HAL_MN10300_AM33 { display "MN10300 AM33 variant" … make { <PREFIX>/lib/target.ld: <PACKAGE>/src/mn10300_am33.ld $(CC) -E -P -Wp,-MD,target.tmp -DEXTRAS=1 -xc $(INCLUDE_PATH) \ $(CFLAGS) -o $@ $< @echo $@ ": \\" > $(notdir $@).deps @tail +2 target.tmp >> $(notdir $@).deps @echo >> $(notdir $@).deps @rm target.tmp } }</PRE ></TD ></TR ></TABLE ><P >For full details of custom build steps and the build process generally, see <A HREF="build.html" >Chapter 4</A >.</P ><P >By default all object files go into the library <TT CLASS="FILENAME" >libtarget.a</TT >. It is possible to override this at the package level using the <SPAN CLASS="PROPERTY" >library</SPAN > property, but this should be avoided since it complicates application development: instead of just linking with a single library for all <SPAN CLASS="APPLICATION" >eCos</SPAN >-related packages, it suddenly becomes necessary to link with several libraries.</P ><P >The <SPAN CLASS="PROPERTY" >include_dir</SPAN > and <SPAN CLASS="PROPERTY" >include_files</SPAN > properties relate to a package's exported header files. By default a package's header files will be exported to the <TT CLASS="FILENAME" >install/include</TT > directory. This is the desired behavior for some packages like the C library, since headers like <TT CLASS="FILENAME" >stdio.h</TT > should exist at that level. However if all header files were to end up in that directory then there would be a significant risk of a name clash. Instead it is better for packages to specify some sub-directory for their exported header files, for example:</P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >cdl_package CYGPKG_INFRA { display "Infrastructure" include_dir cyg/infra … }</PRE ></TD ></TR ></TABLE ><P >The various header files exported by the infrastructure, for example <TT CLASS="FILENAME" >cyg_ass.h</TT > and <TT CLASS="FILENAME" >cyg_trac.h</TT > will now end up in the <TT CLASS="FILENAME" >install/include/cyg/infra</TT > sub-directory, where a name clash is very unlikely.</P ><P >For packages which follow the <A HREF="package.html#PACKAGE.HIERARCHY" >directory layout conventions</A > the component framework will assume that the package's <TT CLASS="FILENAME" >include</TT > sub-directory contains all exported header files. If this is not the case, for example because the package is sufficiently simple that the layout convention is inappropriate, then the exported header files can be listed explicitly in an <SPAN CLASS="PROPERTY" >include_files</SPAN > property.</P ></DIV ><DIV CLASS="SECT2" ><H2 CLASS="SECT2" ><A NAME="LANGUAGE.PROPERTIES.MISCELLANEOUS">Miscellaneous Properties</H2 ><P >The <A HREF="ref.hardware.html" ><SPAN CLASS="PROPERTY" >hardware</SPAN ></A > property is only relevant to packages. Some packages such as device drivers and HAL packages are hardware-specific, and generally it makes no sense to add such packages to a configuration unless the corresponding hardware is present on your target system. Typically hardware package selection happens automatically when you select your target. The <SPAN CLASS="PROPERTY" >hardware</SPAN > property should be used to identify a hardware-specific package, and does not take any arguments.</P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >cdl_package CYGPKG_HAL_MIPS { display "MIPS architecture" parent CYGPKG_HAL hardware include_dir cyg/hal define_header hal_mips.h … }</PRE ></TD ></TR ></TABLE ><P >At present the <SPAN CLASS="PROPERTY" >hardware</SPAN > property is largely ignored by the component framework. This may change in future releases.</P ></DIV ></DIV ><DIV CLASS="NAVFOOTER" ><HR ALIGN="LEFT" WIDTH="100%"><TABLE SUMMARY="Footer navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" ><A HREF="language.commands.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="cdl-guide.html" ACCESSKEY="H" >Home</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" ><A HREF="language.naming.html" ACCESSKEY="N" >Next</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" >CDL Commands</TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="language.html" ACCESSKEY="U" >Up</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" >Option Naming Convention</TD ></TR ></TABLE ></DIV ></BODY ></HTML >
Go to most recent revision | Compare with Previous | Blame | View Log