changeset
first version of an XML documentation - fixes #266
Mon, 02 Oct 2023 18:07:37 +0200
- author
- Mike Becker <universe@uap-core.de>
- date
- Mon, 02 Oct 2023 18:07:37 +0200
- changeset 80
- e55f318a8b8b
- parent 79
- ef0635b78b7b
- child 81
- ea79a383ad75
first version of an XML documentation - fixes #266
| uwproj.xsd | file | annotate | diff | comparison | revisions |
--- a/uwproj.xsd Mon Oct 02 16:55:40 2023 +0200 +++ b/uwproj.xsd Mon Oct 02 18:07:37 2023 +0200 @@ -8,6 +8,14 @@ <xs:element name="project" type="ProjectType"/> <xs:complexType name="ProjectType"> + <xs:annotation> + <xs:documentation> + The root element of an uwproj project. + Consists of an optional <code>config</code> element + and an arbitrary number of <code>dependency</code> + and <code>target</code> elements. + </xs:documentation> + </xs:annotation> <xs:sequence> <xs:element name="config" type="ConfigType" minOccurs="0"/> <xs:element name="dependency" type="DependencyType" minOccurs="0" maxOccurs="unbounded"/> @@ -16,12 +24,31 @@ </xs:complexType> <xs:complexType name="ConfigType"> + <xs:annotation> + <xs:documentation> + The configuration section. + Consists of an arbitrary number of <code>var</code> elements. + </xs:documentation> + </xs:annotation> <xs:sequence> <xs:element name="var" type="ConfigVarType" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> <xs:complexType name="ConfigVarType"> + <xs:annotation> + <xs:documentation> + The definition of a configuration variable. + <p> + Configuration variables are supposed to be used in the configure script and are also + written to the resulting config file (in contrast to make variables, which are only + written to the config file). + The <code>name</code> attribute is mandatory, the value is defined by the text body of the element. + The optional Boolean <code>exec</code> attribute (false by default) controls, whether the entire + definition is automatically executed under command substitution. + </p> + </xs:documentation> + </xs:annotation> <xs:simpleContent> <xs:extension base="xs:string"> <xs:attribute name="name" type="xs:string" use="required"/> @@ -31,6 +58,13 @@ </xs:complexType> <xs:complexType name="PkgConfigType"> + <xs:annotation> + <xs:documentation> + Instructs configure to invoke <code>pkg-config</code>, if present on the system, to determine + compiler and linker flags. The text body of this element defines the package name to search. + To constrain the allowed versions, use the attributes <code>atleast, exact, max</code>. + </xs:documentation> + </xs:annotation> <xs:simpleContent> <xs:extension base="xs:string"> <xs:attribute name="atleast" type="xs:string"/> @@ -41,6 +75,12 @@ </xs:complexType> <xs:simpleType name="LangType"> + <xs:annotation> + <xs:documentation> + Requests a compiler for the specified language. Allowed values are + c, cpp. + </xs:documentation> + </xs:annotation> <xs:restriction base="xs:string"> <xs:enumeration value="c"/> <xs:enumeration value="cpp"/> @@ -48,14 +88,40 @@ </xs:simpleType> <xs:complexType name="DependencyType"> + <xs:annotation> + <xs:documentation> + Declares a dependency. + <p> + If the optional <code>name</code> attribute is omitted, the dependency is global + and must be satisfied, otherwise configuration shall fail. + A <em>named dependency</em> can be referenced by a target (or is implicitly referenced + by the default target, if no targets are specified). + Multiple declarations for the same named dependency may exist, in which case each declaration + is checked one after another, until one block is satisfied. The result of the first satisfied + dependency declaration is supposed to be applied to the config file. + </p> + <p> + The optional <code>platform</code> attribute may specify a <em>single</em> platform identifier and + the optional <code>not</code> attribute may specify a comma-separated list of platform identifiers. + The configure script shall skip this dependency declaration if the detected platform is not + matching the filter specification of these attributes. + </p> + </xs:documentation> + </xs:annotation> <xs:choice minOccurs="0" maxOccurs="unbounded"> <xs:element name="lang" type="LangType"/> <xs:element name="cflags" type="FlagsType"/> <xs:element name="cxxflags" type="FlagsType"/> <xs:element name="ldflags" type="FlagsType"/> <xs:element name="pkgconfig" type="PkgConfigType"/> - <xs:element name="test" type="xs:string"/> - <xs:element name="make" type="xs:string"/> + <xs:element name="test" type="xs:string"> + <xs:annotation> + <xs:documentation> + Specifies a custom command that shall be executed to test whether this dependency is satisfied. + </xs:documentation> + </xs:annotation> + </xs:element> + <xs:element name="make" type="MakeVarType"/> </xs:choice> <xs:attribute name="name" type="xs:string"/> <xs:attribute name="platform" type="xs:string"/> @@ -63,6 +129,13 @@ </xs:complexType> <xs:complexType name="FlagsType"> + <xs:annotation> + <xs:documentation> + Instructs configure to append the contents of the element's body to the respective flags variable. + If the optional <code>exec</code> flag is set to <code>true</code>, the contents are supposed to be + executed under command substitution <em>at configuration time</em> before they are applied. + </xs:documentation> + </xs:annotation> <xs:simpleContent> <xs:extension base="xs:string"> <xs:attribute name="exec" type="xs:boolean" default="false"/> @@ -71,6 +144,25 @@ </xs:complexType> <xs:complexType name="TargetType"> + <xs:annotation> + <xs:documentation> + Declares a build target that is supposed to be configured. + <p> + If no build target is declared explicitly, an implicit default + target is generated, which has the <code>alldependencies</code> + flag set. + </p> + <p> + The optional <code>name</code> attribute is also used to generate a prefix + for the compiler and linker flags variables. + Furthermore, a target may consist of an arbitrary number of <code>feature</code>, + <code>option</code>, and <code>define</code> elements. + Named dependencies can be listed (separated by comma) in the <code>dependencies</code> + element. If this target shall use <em>all</em> available named dependencies, the empty + element <code>alldependencies</code> can be used as a shortcut. + </p> + </xs:documentation> + </xs:annotation> <xs:choice minOccurs="0" maxOccurs="unbounded"> <xs:element name="feature" type="FeatureType"/> <xs:element name="option" type="OptionType"/> @@ -84,6 +176,18 @@ </xs:complexType> <xs:complexType name="FeatureType"> + <xs:annotation> + <xs:documentation> + Declares an optional feature, that can be enabled during configuration, if all + <code>dependencies</code> are satisfied. + If a feature is enabled, all <code>define</code> and <code>make</code> definitions are + supposed to be applied to the config file. + In case the optional <code>default</code> attribute is set to true, the feature is enabled by default + and is supposed to be automatically disabled (without error) when the dependencies are not satisfied. + The name that is supposed to be used for the --enable and --disable arguments can be optionally + specified with the <code>arg</code> attribute. Otherwise, the <code>name</code> is used by default. + </xs:documentation> + </xs:annotation> <xs:choice minOccurs="0" maxOccurs="unbounded"> <xs:group ref="TargetDataGroup"/> </xs:choice> @@ -93,6 +197,17 @@ </xs:complexType> <xs:complexType name="OptionType"> + <xs:annotation> + <xs:documentation> + Declares a configuration option. + The option argument name is specified with the <code>arg</code> attribute. + Then, the children of this element specify possible <code>values</code> by defining the conditions + (in terms of dependencies) and effects (in terms of defines and make variables) of each value. + Finally, a set of <code>default</code>s is specified which supposed to automagically select the most + appropriate value for a specific platform under the available dependencies (in case the option is not + explicitly specified by using the command line argument). + </xs:documentation> + </xs:annotation> <xs:sequence> <xs:element name="value" type="OptionValueType" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="default" type="OptionDefaultType" minOccurs="0" maxOccurs="unbounded"/> @@ -101,6 +216,12 @@ </xs:complexType> <xs:complexType name="OptionValueType"> + <xs:annotation> + <xs:documentation> + Declares a possible value for the option (in the <code>str</code> attribute) and + the conditions (<code>dependencies</code>) and effects, the value has. + </xs:documentation> + </xs:annotation> <xs:choice minOccurs="0" maxOccurs="unbounded"> <xs:group ref="TargetDataGroup"/> </xs:choice> @@ -108,6 +229,14 @@ </xs:complexType> <xs:complexType name="OptionDefaultType"> + <xs:annotation> + <xs:documentation> + Specifies a default value for this option. Multiple default values can be specified, in which case + they are checked one after another for availability. With the optional <code>platform</code> attribute, + the default value can be constrained to a <em>single</em> specific platform and is supposed to be + skipped by configure, when this platform is not detected. + </xs:documentation> + </xs:annotation> <xs:attribute name="value" type="xs:string" use="required"/> <xs:attribute name="platform" type="xs:string"/> </xs:complexType> @@ -116,16 +245,37 @@ <xs:choice> <xs:element name="define" type="DefineType" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="dependencies" type="DependenciesType" minOccurs="0" maxOccurs="unbounded"/> - <xs:element name="make" type="xs:string" minOccurs="0" maxOccurs="unbounded"/> + <xs:element name="make" type="MakeVarType" minOccurs="0" maxOccurs="unbounded"/> </xs:choice> </xs:group> <xs:complexType name="DefineType"> + <xs:annotation> + <xs:documentation> + Specifies C/C++ pre-processor definitions that are supposed to + be appended to the compiler flags, if supported. + (Note: for example, Fortran also supports C/C++ style pre-processor definitions under + certain circumstances) + </xs:documentation> + </xs:annotation> <xs:attribute name="name" type="xs:string" use="required"/> <xs:attribute name="value" type="xs:string"/> </xs:complexType> <xs:simpleType name="DependenciesType"> + <xs:annotation> + <xs:documentation>A comma-separated list of named dependencies.</xs:documentation> + </xs:annotation> + <xs:restriction base="xs:string"/> + </xs:simpleType> + + <xs:simpleType name="MakeVarType"> + <xs:annotation> + <xs:documentation> + The text contents in the body of this element are supposed to be appended literally + to the config file without prior processing. + </xs:documentation> + </xs:annotation> <xs:restriction base="xs:string"/> </xs:simpleType> </xs:schema> \ No newline at end of file
