1.1 --- a/make/uwproj.xsd Fri Oct 06 21:21:10 2023 +0200
1.2 +++ b/make/uwproj.xsd Mon Oct 30 17:40:34 2023 +0100
1.3 @@ -8,6 +8,14 @@
1.4 <xs:element name="project" type="ProjectType"/>
1.5
1.6 <xs:complexType name="ProjectType">
1.7 + <xs:annotation>
1.8 + <xs:documentation>
1.9 + The root element of an uwproj project.
1.10 + Consists of an optional <code>config</code> element
1.11 + and an arbitrary number of <code>dependency</code>
1.12 + and <code>target</code> elements.
1.13 + </xs:documentation>
1.14 + </xs:annotation>
1.15 <xs:sequence>
1.16 <xs:element name="config" type="ConfigType" minOccurs="0"/>
1.17 <xs:element name="dependency" type="DependencyType" minOccurs="0" maxOccurs="unbounded"/>
1.18 @@ -16,12 +24,31 @@
1.19 </xs:complexType>
1.20
1.21 <xs:complexType name="ConfigType">
1.22 + <xs:annotation>
1.23 + <xs:documentation>
1.24 + The configuration section.
1.25 + Consists of an arbitrary number of <code>var</code> elements.
1.26 + </xs:documentation>
1.27 + </xs:annotation>
1.28 <xs:sequence>
1.29 <xs:element name="var" type="ConfigVarType" minOccurs="0" maxOccurs="unbounded"/>
1.30 </xs:sequence>
1.31 </xs:complexType>
1.32
1.33 <xs:complexType name="ConfigVarType">
1.34 + <xs:annotation>
1.35 + <xs:documentation>
1.36 + The definition of a configuration variable.
1.37 + <p>
1.38 + Configuration variables are supposed to be used in the configure script and are also
1.39 + written to the resulting config file (in contrast to make variables, which are only
1.40 + written to the config file).
1.41 + The <code>name</code> attribute is mandatory, the value is defined by the text body of the element.
1.42 + The optional Boolean <code>exec</code> attribute (false by default) controls, whether the entire
1.43 + definition is automatically executed under command substitution.
1.44 + </p>
1.45 + </xs:documentation>
1.46 + </xs:annotation>
1.47 <xs:simpleContent>
1.48 <xs:extension base="xs:string">
1.49 <xs:attribute name="name" type="xs:string" use="required"/>
1.50 @@ -31,6 +58,13 @@
1.51 </xs:complexType>
1.52
1.53 <xs:complexType name="PkgConfigType">
1.54 + <xs:annotation>
1.55 + <xs:documentation>
1.56 + Instructs configure to invoke <code>pkg-config</code>, if present on the system, to determine
1.57 + compiler and linker flags. The text body of this element defines the package name to search.
1.58 + To constrain the allowed versions, use the attributes <code>atleast, exact, max</code>.
1.59 + </xs:documentation>
1.60 + </xs:annotation>
1.61 <xs:simpleContent>
1.62 <xs:extension base="xs:string">
1.63 <xs:attribute name="atleast" type="xs:string"/>
1.64 @@ -41,6 +75,12 @@
1.65 </xs:complexType>
1.66
1.67 <xs:simpleType name="LangType">
1.68 + <xs:annotation>
1.69 + <xs:documentation>
1.70 + Requests a compiler for the specified language. Allowed values are
1.71 + c, cpp.
1.72 + </xs:documentation>
1.73 + </xs:annotation>
1.74 <xs:restriction base="xs:string">
1.75 <xs:enumeration value="c"/>
1.76 <xs:enumeration value="cpp"/>
1.77 @@ -48,14 +88,40 @@
1.78 </xs:simpleType>
1.79
1.80 <xs:complexType name="DependencyType">
1.81 + <xs:annotation>
1.82 + <xs:documentation>
1.83 + Declares a dependency.
1.84 + <p>
1.85 + If the optional <code>name</code> attribute is omitted, the dependency is global
1.86 + and must be satisfied, otherwise configuration shall fail.
1.87 + A <em>named dependency</em> can be referenced by a target (or is implicitly referenced
1.88 + by the default target, if no targets are specified).
1.89 + Multiple declarations for the same named dependency may exist, in which case each declaration
1.90 + is checked one after another, until one block is satisfied. The result of the first satisfied
1.91 + dependency declaration is supposed to be applied to the config file.
1.92 + </p>
1.93 + <p>
1.94 + The optional <code>platform</code> attribute may specify a <em>single</em> platform identifier and
1.95 + the optional <code>not</code> attribute may specify a comma-separated list of platform identifiers.
1.96 + The configure script shall skip this dependency declaration if the detected platform is not
1.97 + matching the filter specification of these attributes.
1.98 + </p>
1.99 + </xs:documentation>
1.100 + </xs:annotation>
1.101 <xs:choice minOccurs="0" maxOccurs="unbounded">
1.102 <xs:element name="lang" type="LangType"/>
1.103 <xs:element name="cflags" type="FlagsType"/>
1.104 <xs:element name="cxxflags" type="FlagsType"/>
1.105 <xs:element name="ldflags" type="FlagsType"/>
1.106 <xs:element name="pkgconfig" type="PkgConfigType"/>
1.107 - <xs:element name="test" type="xs:string"/>
1.108 - <xs:element name="make" type="xs:string"/>
1.109 + <xs:element name="test" type="xs:string">
1.110 + <xs:annotation>
1.111 + <xs:documentation>
1.112 + Specifies a custom command that shall be executed to test whether this dependency is satisfied.
1.113 + </xs:documentation>
1.114 + </xs:annotation>
1.115 + </xs:element>
1.116 + <xs:element name="make" type="MakeVarType"/>
1.117 </xs:choice>
1.118 <xs:attribute name="name" type="xs:string"/>
1.119 <xs:attribute name="platform" type="xs:string"/>
1.120 @@ -63,6 +129,13 @@
1.121 </xs:complexType>
1.122
1.123 <xs:complexType name="FlagsType">
1.124 + <xs:annotation>
1.125 + <xs:documentation>
1.126 + Instructs configure to append the contents of the element's body to the respective flags variable.
1.127 + If the optional <code>exec</code> flag is set to <code>true</code>, the contents are supposed to be
1.128 + executed under command substitution <em>at configuration time</em> before they are applied.
1.129 + </xs:documentation>
1.130 + </xs:annotation>
1.131 <xs:simpleContent>
1.132 <xs:extension base="xs:string">
1.133 <xs:attribute name="exec" type="xs:boolean" default="false"/>
1.134 @@ -71,6 +144,25 @@
1.135 </xs:complexType>
1.136
1.137 <xs:complexType name="TargetType">
1.138 + <xs:annotation>
1.139 + <xs:documentation>
1.140 + Declares a build target that is supposed to be configured.
1.141 + <p>
1.142 + If no build target is declared explicitly, an implicit default
1.143 + target is generated, which has the <code>alldependencies</code>
1.144 + flag set.
1.145 + </p>
1.146 + <p>
1.147 + The optional <code>name</code> attribute is also used to generate a prefix
1.148 + for the compiler and linker flags variables.
1.149 + Furthermore, a target may consist of an arbitrary number of <code>feature</code>,
1.150 + <code>option</code>, and <code>define</code> elements.
1.151 + Named dependencies can be listed (separated by comma) in the <code>dependencies</code>
1.152 + element. If this target shall use <em>all</em> available named dependencies, the empty
1.153 + element <code>alldependencies</code> can be used as a shortcut.
1.154 + </p>
1.155 + </xs:documentation>
1.156 + </xs:annotation>
1.157 <xs:choice minOccurs="0" maxOccurs="unbounded">
1.158 <xs:element name="feature" type="FeatureType"/>
1.159 <xs:element name="option" type="OptionType"/>
1.160 @@ -84,6 +176,18 @@
1.161 </xs:complexType>
1.162
1.163 <xs:complexType name="FeatureType">
1.164 + <xs:annotation>
1.165 + <xs:documentation>
1.166 + Declares an optional feature, that can be enabled during configuration, if all
1.167 + <code>dependencies</code> are satisfied.
1.168 + If a feature is enabled, all <code>define</code> and <code>make</code> definitions are
1.169 + supposed to be applied to the config file.
1.170 + In case the optional <code>default</code> attribute is set to true, the feature is enabled by default
1.171 + and is supposed to be automatically disabled (without error) when the dependencies are not satisfied.
1.172 + The name that is supposed to be used for the --enable and --disable arguments can be optionally
1.173 + specified with the <code>arg</code> attribute. Otherwise, the <code>name</code> is used by default.
1.174 + </xs:documentation>
1.175 + </xs:annotation>
1.176 <xs:choice minOccurs="0" maxOccurs="unbounded">
1.177 <xs:group ref="TargetDataGroup"/>
1.178 </xs:choice>
1.179 @@ -93,14 +197,31 @@
1.180 </xs:complexType>
1.181
1.182 <xs:complexType name="OptionType">
1.183 + <xs:annotation>
1.184 + <xs:documentation>
1.185 + Declares a configuration option.
1.186 + The option argument name is specified with the <code>arg</code> attribute.
1.187 + Then, the children of this element specify possible <code>values</code> by defining the conditions
1.188 + (in terms of dependencies) and effects (in terms of defines and make variables) of each value.
1.189 + Finally, a set of <code>default</code>s is specified which supposed to automagically select the most
1.190 + appropriate value for a specific platform under the available dependencies (in case the option is not
1.191 + explicitly specified by using the command line argument).
1.192 + </xs:documentation>
1.193 + </xs:annotation>
1.194 <xs:sequence>
1.195 <xs:element name="value" type="OptionValueType" minOccurs="0" maxOccurs="unbounded"/>
1.196 <xs:element name="default" type="OptionDefaultType" minOccurs="0" maxOccurs="unbounded"/>
1.197 </xs:sequence>
1.198 - <xs:attribute name="arg" type="xs:string"/>
1.199 + <xs:attribute name="arg" type="xs:string" use="required"/>
1.200 </xs:complexType>
1.201
1.202 <xs:complexType name="OptionValueType">
1.203 + <xs:annotation>
1.204 + <xs:documentation>
1.205 + Declares a possible value for the option (in the <code>str</code> attribute) and
1.206 + the conditions (<code>dependencies</code>) and effects, the value has.
1.207 + </xs:documentation>
1.208 + </xs:annotation>
1.209 <xs:choice minOccurs="0" maxOccurs="unbounded">
1.210 <xs:group ref="TargetDataGroup"/>
1.211 </xs:choice>
1.212 @@ -108,6 +229,14 @@
1.213 </xs:complexType>
1.214
1.215 <xs:complexType name="OptionDefaultType">
1.216 + <xs:annotation>
1.217 + <xs:documentation>
1.218 + Specifies a default value for this option. Multiple default values can be specified, in which case
1.219 + they are checked one after another for availability. With the optional <code>platform</code> attribute,
1.220 + the default value can be constrained to a <em>single</em> specific platform and is supposed to be
1.221 + skipped by configure, when this platform is not detected.
1.222 + </xs:documentation>
1.223 + </xs:annotation>
1.224 <xs:attribute name="value" type="xs:string" use="required"/>
1.225 <xs:attribute name="platform" type="xs:string"/>
1.226 </xs:complexType>
1.227 @@ -116,16 +245,37 @@
1.228 <xs:choice>
1.229 <xs:element name="define" type="DefineType" minOccurs="0" maxOccurs="unbounded"/>
1.230 <xs:element name="dependencies" type="DependenciesType" minOccurs="0" maxOccurs="unbounded"/>
1.231 - <xs:element name="make" type="xs:string" minOccurs="0" maxOccurs="unbounded"/>
1.232 + <xs:element name="make" type="MakeVarType" minOccurs="0" maxOccurs="unbounded"/>
1.233 </xs:choice>
1.234 </xs:group>
1.235
1.236 <xs:complexType name="DefineType">
1.237 + <xs:annotation>
1.238 + <xs:documentation>
1.239 + Specifies C/C++ pre-processor definitions that are supposed to
1.240 + be appended to the compiler flags, if supported.
1.241 + (Note: for example, Fortran also supports C/C++ style pre-processor definitions under
1.242 + certain circumstances)
1.243 + </xs:documentation>
1.244 + </xs:annotation>
1.245 <xs:attribute name="name" type="xs:string" use="required"/>
1.246 <xs:attribute name="value" type="xs:string"/>
1.247 </xs:complexType>
1.248
1.249 <xs:simpleType name="DependenciesType">
1.250 + <xs:annotation>
1.251 + <xs:documentation>A comma-separated list of named dependencies.</xs:documentation>
1.252 + </xs:annotation>
1.253 + <xs:restriction base="xs:string"/>
1.254 + </xs:simpleType>
1.255 +
1.256 + <xs:simpleType name="MakeVarType">
1.257 + <xs:annotation>
1.258 + <xs:documentation>
1.259 + The text contents in the body of this element are supposed to be appended literally
1.260 + to the config file without prior processing.
1.261 + </xs:documentation>
1.262 + </xs:annotation>
1.263 <xs:restriction base="xs:string"/>
1.264 </xs:simpleType>
1.265 </xs:schema>
1.266 \ No newline at end of file
