tools/build/doc/src/type.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
   3   "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
   4
   5 <section id="bbv2.reference.modules.type">
   6
   7   <title>type</title>
   8   <indexterm>
   9     <primary>type</primary>
  10     <secondary>module</secondary>
  11   </indexterm>
  12
  13   <para>
  14     Deals with target type declaration and defines target class which supports
  15     typed targets.
  16   </para>
  17
  18   <orderedlist>
  19
  20     <listitem id="bbv2.reference.modules.type.register">
  21       <indexterm zone="bbv2.reference.modules.type.register">
  22         <primary>register</primary>
  23         <secondary>type</secondary>
  24       </indexterm>
  25       <code language="jam">rule register ( type : suffixes * : base-type ? )</code>
  26       <para>
  27         Registers a target type, possible derived from a
  28         <code language="jam">base-type</code>.  Providing a list
  29         of suffixes here is a shortcut for separately calling the
  30         <link linkend="bbv2.reference.modules.type.register-suffixes">register-suffixes</link>
  31         rule with the given suffixes and the
  32         <link linkend="bbv2.reference.modules.type.set-generated-target-suffix">set-generated-target-suffix</link>
  33         rule with the first given suffix.
  34       </para>
  35     </listitem>
  36
  37     <listitem id="bbv2.reference.modules.type.register-suffixes">
  38       <indexterm zone="bbv2.reference.modules.type.register-suffixes">
  39         <primary>register-suffixes</primary>
  40       </indexterm>
  41       <code language="jam">rule register-suffixes ( suffixes + : type )</code>
  42       <para>
  43         Specifies that files with suffix from <code language="jam">suffixes</code>
  44         be recognized as targets of  type <code language="jam">type</code>.
  45         Issues an error if a different type is already specified for any
  46         of the suffixes.
  47       </para>
  48     </listitem>
  49
  50     <listitem id="bbv2.reference.modules.type.registered">
  51       <indexterm zone="bbv2.reference.modules.type.registered">
  52         <primary>registered</primary>
  53       </indexterm>
  54       <code language="jam">rule registered ( type )</code>
  55       <para>Returns true iff type has been registered.</para>
  56     </listitem>
  57
  58     <listitem id="bbv2.reference.modules.type.validate">
  59       <indexterm zone="bbv2.reference.modules.type.validate">
  60         <primary>validate</primary>
  61       </indexterm>
  62       <code language="jam">rule validate ( type )</code>
  63       <para>Issues an error if <code lang="jam">type</code> is unknown.</para>
  64     </listitem>
  65
  66     <listitem id="bbv2.reference.modules.type.set-scanner">
  67       <indexterm zone="bbv2.reference.modules.type.set-scanner">
  68         <primary>set-scanner</primary>
  69       </indexterm>
  70       <code language="jam">rule set-scanner ( type : scanner )</code>
  71       <para>Sets a scanner class that will be used for this type.</para>
  72     </listitem>
  73
  74     <listitem id="bbv2.reference.modules.type.get-scanner">
  75       <indexterm zone="bbv2.reference.modules.type.get-scanner">
  76         <primary>get-scanner</primary>
  77       </indexterm>
  78       <code language="jam">rule get-scanner ( type : property-set )</code>
  79       <para>
  80         Returns a scanner instance appropriate to <code language="jam">type</code>
  81         and <code language="jam">property-set</code>.
  82       </para>
  83     </listitem>
  84
  85     <listitem id="bbv2.reference.modules.type.base">
  86       <indexterm zone="bbv2.reference.modules.type.base">
  87         <primary>base</primary>
  88       </indexterm>
  89       <code language="jam">rule base ( type )</code>
  90       <para>
  91         Returns a base type for the given type or nothing in case the given
  92         type is not derived.
  93       </para>
  94     </listitem>
  95
  96     <listitem id="bbv2.reference.modules.type.all-bases">
  97       <indexterm zone="bbv2.reference.modules.type.all-bases">
  98         <primary>all-bases</primary>
  99       </indexterm>
 100       <code language="jam">rule all-bases ( type )</code>
 101       <para>
 102         Returns the given type and all of its base types in order of
 103         their distance from type.
 104       </para>
 105     </listitem>
 106
 107     <listitem id="bbv2.reference.modules.type.all-derived">
 108       <indexterm zone="bbv2.reference.modules.type.all-derived">
 109         <primary>all-derived</primary>
 110       </indexterm>
 111       <code language="jam">rule all-derived ( type )</code>
 112       <para>
 113         Returns the given type and all of its derived types in order
 114         of their distance from type.
 115       </para>
 116     </listitem>
 117
 118     <listitem id="bbv2.reference.modules.type.is-derived">
 119       <indexterm zone="bbv2.reference.modules.type.is-derived">
 120         <primary>is-derived</primary>
 121       </indexterm>
 122       <code language="jam">rule is-derived ( type base )</code>
 123       <para>
 124         Returns true if <code language="jam">type</code> is equal to
 125         <code language="jam">base</code> or has <code language="jam">base</code>
 126         as its direct or indirect base.
 127       </para>
 128     </listitem>
 129
 130     <listitem id="bbv2.reference.modules.type.set-generated-target-suffix">
 131       <indexterm zone="bbv2.reference.modules.type.set-generated-target-suffix">
 132         <primary>set-generated-target-suffix</primary>
 133       </indexterm>
 134       <code language="jam">rule set-generated-target-suffix ( type : properties * : suffix )</code>
 135       <para>
 136         Sets a file suffix to be used when generating a target of <code language="jam">type</code> with the
 137         specified properties. Can be called with no properties if no suffix has
 138         already been specified for the <code language="jam">type</code>. The <code language="jam">suffix</code> parameter can be an empty
 139         string (<code language="jam">""</code>) to indicate that no suffix should be used.
 140       </para>
 141
 142       <para>
 143         Note that this does not cause files with <code language="jam">suffix</code>
 144         to be automatically recognized as being of <code language="jam">type</code>.
 145         Two different types can use the same suffix for their generated files
 146         but only one type can be auto-detected for a file with that suffix.
 147         User should explicitly specify which one using the
 148         <link linkend="bbv2.reference.modules.type.register-suffixes">register-suffixes</link>
 149         rule.
 150       </para>
 151     </listitem>
 152
 153     <listitem id="bbv2.reference.modules.type.change-generated-target-suffix">
 154       <indexterm zone="bbv2.reference.modules.type.change-generated-target-suffix">
 155         <primary>change-generated-target-suffix</primary>
 156       </indexterm>
 157       <code language="jam">rule change-generated-target-suffix ( type : properties * : suffix )</code>
 158       <para>
 159         Change the suffix previously registered for this type/properties
 160         combination. If suffix is not yet specified, sets it.
 161       </para>
 162     </listitem>
 163
 164     <listitem id="bbv2.reference.modules.type.generated-target-suffix">
 165       <indexterm zone="bbv2.reference.modules.type.generated-target-suffix">
 166         <primary>generated-target-suffix</primary>
 167       </indexterm>
 168       <code language="jam">rule generated-target-suffix ( type : property-set )</code>
 169       <para>
 170         Returns the suffix used when generating a file of
 171         <code language="jam">type</code> with the given properties.
 172       </para>
 173     </listitem>
 174
 175     <listitem id="bbv2.reference.modules.type.set-generated-target-prefix">
 176       <indexterm zone="bbv2.reference.modules.type.set-generated-target-prefix">
 177         <primary>set-generated-target-prefix</primary>
 178       </indexterm>
 179       <code language="jam">rule set-generated-target-prefix ( type : properties * : prefix )</code>
 180       <para>
 181         Sets a target prefix that should be used when generating targets of
 182         <code language="jam">type</code> with the specified properties. Can
 183         be called with empty properties if no prefix for
 184         <code language="jam">type</code> has been specified yet.
 185       </para>
 186
 187       <para>
 188         The <code language="jam">prefix</code> parameter can be empty string
 189         (<code language="jam">""</code>) to indicate that no prefix
 190         should be used.
 191       </para>
 192
 193       <para>
 194         Usage example: library names use the <code language="jam">"lib"</code>
 195         prefix on unix.
 196       </para>
 197     </listitem>
 198
 199     <listitem id="bbv2.reference.modules.type.change-generated-target-prefix">
 200       <indexterm zone="bbv2.reference.modules.type.change-generated-target-prefix">
 201         <primary>change-generated-target-prefix</primary>
 202       </indexterm>
 203       <code language="jam">rule change-generated-target-prefix ( type : properties * : prefix )</code>
 204       <para>
 205         Change the prefix previously registered for this type/properties
 206         combination. If prefix is not yet specified, sets it.
 207       </para>
 208     </listitem>
 209
 210     <listitem id="bbv2.reference.modules.type.generated-target-prefix">
 211       <indexterm zone="bbv2.reference.modules.type.generated-target-prefix">
 212         <primary>generated-target-prefix</primary>
 213       </indexterm>
 214       <code language="jam">rule generated-target-prefix ( type : property-set )</code>
 215       <para>
 216         Returns the prefix used when generating a file of
 217         <code language="jam">type</code> with the given properties.
 218       </para>
 219     </listitem>
 220
 221     <listitem id="bbv2.reference.modules.type.type">
 222       <indexterm zone="bbv2.reference.modules.type.type">
 223         <primary>type</primary>
 224         <secondary>rule</secondary>
 225       </indexterm>
 226       <code language="jam">rule type ( filename )</code>
 227       <para>
 228         Returns file type given its name. If there are several
 229         dots in filename, tries each suffix. E.g. for name of
 230         "file.so.1.2" suffixes "2", "1", and "so" will be tried.
 231       </para>
 232     </listitem>
 233
 234   </orderedlist>
 235
 236 </section>