diff options
Diffstat (limited to 'tools/build/doc/src/path.xml')
| -rw-r--r-- | tools/build/doc/src/path.xml | 249 |
1 files changed, 249 insertions, 0 deletions
diff --git a/tools/build/doc/src/path.xml b/tools/build/doc/src/path.xml new file mode 100644 index 000000000..f11906db5 --- /dev/null +++ b/tools/build/doc/src/path.xml @@ -0,0 +1,249 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" + "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> + +<section id="bbv2.reference.modules.path"> + + <title>path</title> + <indexterm> + <primary>path</primary> + <secondary>module</secondary> + </indexterm> + + <para> + Performs various path manipulations. Paths are always in a 'normalized' + representation. In it, a path may be either: + + <itemizedlist> + <listitem><para><code>'.'</code>, or</para></listitem> + <listitem> + <para> + <code>['/'] [ ( '..' '/' )* (token '/')* token ]</code> + </para> + </listitem> + </itemizedlist> + + In plain english, a path can be rooted, <code>'..'</code> + elements are allowed only at the beginning, and it never + ends in slash, except for the path consisting of slash only. + </para> + + <orderedlist> + + <listitem id="bbv2.reference.modules.path.make"> + <indexterm zone="bbv2.reference.modules.path.make"> + <primary>make</primary> + <secondary>path</secondary> + </indexterm> + <code language="jam">rule make ( native )</code> + <para>Converts the native path into normalized form.</para> + </listitem> + + <listitem id="bbv2.reference.modules.path.native"> + <indexterm zone="bbv2.reference.modules.path.native"> + <primary>native</primary> + </indexterm> + <code language="jam">rule native ( path )</code> + <para>Builds the native representation of the path.</para> + </listitem> + + <listitem id="bbv2.reference.modules.path.is-rooted"> + <indexterm zone="bbv2.reference.modules.path.is-rooted"> + <primary>is-rooted</primary> + </indexterm> + <code language="jam">rule is-rooted ( path )</code> + <para>Tests if a path is rooted.</para> + </listitem> + + <listitem id="bbv2.reference.modules.path.has-parent"> + <indexterm zone="bbv2.reference.modules.path.has-parent"> + <primary>has-parent</primary> + </indexterm> + <code language="jam">rule has-parent ( path )</code> + <para>Tests if a path has a parent.</para> + </listitem> + + <listitem id="bbv2.reference.modules.path.basename"> + <indexterm zone="bbv2.reference.modules.path.basename"> + <primary>basename</primary> + </indexterm> + <code language="jam">rule basename ( path )</code> + <para>Returns the path without any directory components.</para> + </listitem> + + <listitem id="bbv2.reference.modules.path.parent"> + <indexterm zone="bbv2.reference.modules.path.parent"> + <primary>parent</primary> + </indexterm> + <code language="jam">rule parent ( path )</code> + <para>Returns the parent directory of the path. If no parent exists, an error is issued.</para> + </listitem> + + <listitem id="bbv2.reference.modules.path.reverse"> + <indexterm zone="bbv2.reference.modules.path.reverse"> + <primary>reverse</primary> + </indexterm> + <code language="jam">rule reverse ( path )</code> + <para> + Returns <code language="jam">path2</code> such that + <code language="jam">[ join path path2 ] = "."</code>. + The path may not contain <code language="jam">".."</code> + element or be rooted. + </para> + </listitem> + + <listitem id="bbv2.reference.modules.path.join"> + <indexterm zone="bbv2.reference.modules.path.join"> + <primary>join</primary> + </indexterm> + <code language="jam">rule join ( elements + )</code> + <para> + Concatenates the passed path elements. Generates an error if any + element other than the first one is rooted. Skips any empty or + undefined path elements. + </para> + </listitem> + + <listitem id="bbv2.reference.modules.path.root"> + <indexterm zone="bbv2.reference.modules.path.root"> + <primary>root</primary> + </indexterm> + <code language="jam">rule root ( path root )</code> + <para> + If <code language="jam">path</code> is relative, it is rooted at + <code language="jam">root</code>. Otherwise, it is unchanged. + </para> + </listitem> + + <listitem id="bbv2.reference.modules.path.pwd"> + <indexterm zone="bbv2.reference.modules.path.pwd"> + <primary>pwd</primary> + </indexterm> + <code language="jam">rule pwd ( )</code> + <para>Returns the current working directory.</para> + </listitem> + + <listitem id="bbv2.reference.modules.path.glob"> + <indexterm zone="bbv2.reference.modules.path.glob"> + <primary>glob</primary> + </indexterm> + <code language="jam">rule glob ( dirs * : patterns + : exclude-patterns * )</code> + <para> + Returns the list of files matching the given pattern in the specified + directory. Both directories and patterns are supplied as portable paths. Each + pattern should be a non-absolute path, and can't contain "." or ".." elements. + Each slash separated element of a pattern can contain the following special + characters: + <itemizedlist> + <listitem> + <para>'?' matches any character</para> + </listitem> + <listitem> + <para>'*' matches an arbitrary number of characters</para> + </listitem> + </itemizedlist> + A file $(d)/e1/e2/e3 (where 'd' is in $(dirs)) matches the pattern p1/p2/p3 if and + only if e1 matches p1, e2 matches p2 and so on. + + For example: +<programlisting language="jam"> +[ glob . : *.cpp ] +[ glob . : */build/Jamfile ] +</programlisting> + </para> + </listitem> + + <listitem id="bbv2.reference.modules.path.glob-tree"> + <indexterm zone="bbv2.reference.modules.path.glob-tree"> + <primary>glob-tree</primary> + </indexterm> + <code language="jam">rule glob-tree ( roots * : patterns + : exclude-patterns * )</code> + <para> + Recursive version of <link linkend="bbv2.reference.modules.path.glob">glob</link>. + Builds the glob of files while also searching in + the subdirectories of the given roots. An optional set of exclusion patterns + will filter out the matching entries from the result. The exclusions also + apply to the subdirectory scanning, such that directories that match the + exclusion patterns will not be searched. + </para> + </listitem> + + <listitem id="bbv2.reference.modules.path.exists"> + <indexterm zone="bbv2.reference.modules.path.exists"> + <primary>exists</primary> + </indexterm> + <code language="jam">rule exists ( file )</code> + <para>Returns true if the specified file exists.</para> + </listitem> + + <listitem id="bbv2.reference.modules.path.all-parents"> + <indexterm zone="bbv2.reference.modules.path.all-parents"> + <primary>all-parents</primary> + </indexterm> + <code language="jam">rule all-parents ( path : upper_limit ? : cwd ? )</code> + <para> + Find out the absolute name of path and return the list of all the parents, + starting with the immediate one. Parents are returned as relative names. If + <code language="jam">upper_limit</code> is specified, directories above it + will be pruned. + </para> + </listitem> + + <listitem id="bbv2.reference.modules.path.glob-in-parents"> + <indexterm zone="bbv2.reference.modules.path.glob-in-parents"> + <primary>glob-in-parents</primary> + </indexterm> + <code language="jam">rule glob-in-parents ( dir : patterns + : upper-limit ? )</code> + <para> + Search for <code language="jam">patterns</code> in parent directories + of <code language="jam">dir</code>, up to and including + <code language="jam">upper_limit</code>, if it is specified, or + till the filesystem root otherwise. + </para> + </listitem> + + <listitem id="bbv2.reference.modules.path.relative"> + <indexterm zone="bbv2.reference.modules.path.relative"> + <primary>relative</primary> + </indexterm> + <code language="jam">rule relative ( child parent : no-error ? )</code> + <para> + Assuming <code language="jam">child</code> is a subdirectory of + <code language="jam">parent</code>, return the relative path from + <code language="jam">parent</code> to <code language="jam">child</code>. + </para> + </listitem> + + <listitem id="bbv2.reference.modules.path.relative-to"> + <indexterm zone="bbv2.reference.modules.path.relative-to"> + <primary>relative-to</primary> + </indexterm> + <code language="jam">rule relative-to ( path1 path2 )</code> + <para>Returns the minimal path to path2 that is relative path1.</para> + </listitem> + + <listitem id="bbv2.reference.modules.path.programs-path"> + <indexterm zone="bbv2.reference.modules.path.programs-path"> + <primary>programs-path</primary> + </indexterm> + <code language="jam">rule programs-path ( )</code> + <para> + Returns the list of paths which are used by the operating system for + looking up programs. + </para> + </listitem> + + <listitem id="bbv2.reference.modules.path.mkdirs"> + <indexterm zone="bbv2.reference.modules.path.mkdirs"> + <primary>mkdirs</primary> + </indexterm> + <code language="jam">rule makedirs ( path )</code> + <para> + Creates a directory and all parent directories that do not + already exist. + </para> + </listitem> + + </orderedlist> + +</section> |