doc/file.README.html in rubu-0.0.4 vs doc/file.README.html in rubu-0.0.5
- old
+ new
@@ -62,37 +62,38 @@
<iframe id="search_frame"></iframe>
<div id="content"><div id='filecontents'>
<h1 id="label-Rubu">Rubu</h1>
-<p><span class='object_link'><a href="Rubu.html" title="Rubu (class)">Rubu</a></span> (Re-Usable Build Utility) is a library for building programs. <span class='object_link'><a href="Rubu.html" title="Rubu (class)">Rubu</a></span>
-is in practice a replacement for Make and Rake type of tools. <span class='object_link'><a href="Rubu.html" title="Rubu (class)">Rubu</a></span> is
+<p><span class='object_link'><a href="Rubu.html" title="Rubu (module)">Rubu</a></span> (Re-Usable Build Utility) is a library for building programs. <span class='object_link'><a href="Rubu.html" title="Rubu (module)">Rubu</a></span>
+is in practice a replacement for Make and Rake type of tools. <span class='object_link'><a href="Rubu.html" title="Rubu (module)">Rubu</a></span> is
targeted to provide means for creating flexible build environments.</p>
<p>Make and Rake are rule and recipe based, and they are very effective when
the build process can be captured to these rules and is fairly fixed.
-<span class='object_link'><a href="Rubu.html" title="Rubu (class)">Rubu</a></span> includes declarations which correspond to rules, but the
+<span class='object_link'><a href="Rubu.html" title="Rubu (module)">Rubu</a></span> includes declarations which correspond to rules, but the
declarations are lower level and provide more control over the behavior.
-<span class='object_link'><a href="Rubu.html" title="Rubu (class)">Rubu</a></span> also provides direct control over when the rules are executed.</p>
+<span class='object_link'><a href="Rubu.html" title="Rubu (module)">Rubu</a></span> also provides direct control over when the rules are executed.</p>
<p>Make and Rake are more compact for the simplest build environments, but
-there is a break-even point where <span class='object_link'><a href="Rubu.html" title="Rubu (class)">Rubu</a></span> becomes more convenient. This is
+there is a break-even point where <span class='object_link'><a href="Rubu.html" title="Rubu (module)">Rubu</a></span> becomes more convenient. This is
likely to happen when the user needs many exceptions to basic rules, also
when other tasks than just build tasks are needed.</p>
-<p><span class='object_link'><a href="Rubu.html" title="Rubu (class)">Rubu</a></span> library can be used from any Ruby program, since it is just a
+<p><span class='object_link'><a href="Rubu.html" title="Rubu (module)">Rubu</a></span> library can be used from any Ruby program, since it is just a
library. It can also be part of a larger program as less significant part
of the overall functionality. From maintenance point of view this can be a
win in many cases.</p>
-<p>The easiest way to get started with <span class='object_link'><a href="Rubu.html" title="Rubu (class)">Rubu</a></span> is to study examples (See:
+<p>The easiest way to get started with <span class='object_link'><a href="Rubu.html" title="Rubu (module)">Rubu</a></span> is to study examples (See:
“Example” chapter below). However for longer term the main concepts are
important as well (See: “Concepts” chapter below).</p>
<h2 id="label-Example">Example</h2>
-<p>Example of <span class='object_link'><a href="Rubu.html" title="Rubu (class)">Rubu</a></span> build program is placed in:</p>
+<p>Example of <span class='object_link'><a href="Rubu.html" title="Rubu (module)">Rubu</a></span> build program is placed in (relative to your installation
+directory), which you should copy over somewhere to execute:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_example'>example</span><span class='op'>/</span><span class='id identifier rubyid_bin'>bin</span><span class='op'>/</span><span class='id identifier rubyid_rubu_example'>rubu_example</span>
</code></pre>
<p>It builds a “hello world” type program which is split into two C source
@@ -116,23 +117,23 @@
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_cat'>cat</span> <span class='id identifier rubyid_example'>example</span><span class='op'>/</span><span class='id identifier rubyid_bin'>bin</span><span class='op'>/</span><span class='id identifier rubyid_rubu_example'>rubu_example</span>
</code></pre>
<p>There are comments which highlight purpose of the build program content.</p>
-<p>Sometimes it is useful to run <span class='object_link'><a href="Rubu.html" title="Rubu (class)">Rubu</a></span> automatically whenever a file changes.
+<p>Sometimes it is useful to run <span class='object_link'><a href="Rubu.html" title="Rubu (module)">Rubu</a></span> automatically whenever a file changes.
Linux provides a facility called <strong>inotify</strong>, which can be
used in Ruby through “rb-inotify” gem. Automatic update example program is
in:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_example'>example</span><span class='op'>/</span><span class='id identifier rubyid_up'>up</span><span class='op'>-</span><span class='id identifier rubyid_to'>to</span><span class='op'>-</span><span class='id identifier rubyid_date'>date</span>
</code></pre>
-<p>This program runs <span class='object_link'><a href="Rubu.html" title="Rubu (class)">Rubu</a></span> each time there is a change in “src” or in “bin”
+<p>This program runs <span class='object_link'><a href="Rubu.html" title="Rubu (module)">Rubu</a></span> each time there is a change in “src” or in “bin”
directory. It compiles and generates C files if necessary. If there are new
compilation requirements coming, before all previous have been completed,
it will continue compilation. When all compilations are done (i.e. none
-pending), it will call <span class='object_link'><a href="Rubu.html" title="Rubu (class)">Rubu</a></span> to perform linking. “up-to-date” displays
+pending), it will call <span class='object_link'><a href="Rubu.html" title="Rubu (module)">Rubu</a></span> to perform linking. “up-to-date” displays
status messages in red and green on the screen. If it is started with “-v”
option the compile commands are visible, and if it is started with “-d”
option, there is extra delay in compilation command.</p>
<pre class="code ruby"><code class="ruby">cd example
@@ -143,17 +144,17 @@
“hello_world.c” (for example), and follow the updates in the terminal where
you started “up-to-date”.</p>
<h2 id="label-Concepts">Concepts</h2>
-<p><span class='object_link'><a href="Rubu.html" title="Rubu (class)">Rubu</a></span> Build Program, RBP, is a Ruby program that uses the <span class='object_link'><a href="Rubu.html" title="Rubu (class)">Rubu</a></span> library.
+<p><span class='object_link'><a href="Rubu.html" title="Rubu (module)">Rubu</a></span> Build Program, RBP, is a Ruby program that uses the <span class='object_link'><a href="Rubu.html" title="Rubu (module)">Rubu</a></span> library.
Typically command line options are accepted to give options for the build
process.</p>
<p>Build programs are about collecting source files and transforming them into
-targets. This process is explicit in <span class='object_link'><a href="Rubu.html" title="Rubu (class)">Rubu</a></span>. Each file, whether it's
-source or target, is collected within the <span class='object_link'><a href="Rubu.html" title="Rubu (class)">Rubu</a></span> build program. The files
+targets. This process is explicit in <span class='object_link'><a href="Rubu.html" title="Rubu (module)">Rubu</a></span>. Each file, whether it's
+source or target, is collected within the <span class='object_link'><a href="Rubu.html" title="Rubu (module)">Rubu</a></span> build program. The files
are converted into <strong>Mark</strong> objects. Basically
<strong>Mark</strong> corresponds to a file, but it includes methods that
make the build process convenient.</p>
<p><strong>Step</strong> is build action that transforms source file(s) to
@@ -186,18 +187,18 @@
<strong>Trail</strong>. <strong>Trail</strong> can be sequential or
parallel. For example, C source to object compilation can be done in
parallel, but linking of objects to executable must occur after all objects
have been created.</p>
-<p><span class='object_link'><a href="Rubu.html" title="Rubu (class)">Rubu</a></span> Build Program includes all of the above, and the last step is to
+<p><span class='object_link'><a href="Rubu.html" title="Rubu (module)">Rubu</a></span> Build Program includes all of the above, and the last step is to
select which <strong>Trail</strong> is executed. There should be at least
“default” <strong>Trail</strong>, and typically there is also a “clean”
<strong>Trail</strong>.</p>
-<p><span class='object_link'><a href="Rubu.html" title="Rubu (class)">Rubu</a></span> supports the configuration spaces: <strong>Order</strong>,
+<p><span class='object_link'><a href="Rubu.html" title="Rubu (module)">Rubu</a></span> supports the configuration spaces: <strong>Order</strong>,
<strong>Var</strong>, and <strong>Info</strong>. <strong>Order</strong> is
-meant to be used for controlling <span class='object_link'><a href="Rubu.html" title="Rubu (class)">Rubu</a></span> itself. For example if user wants
+meant to be used for controlling <span class='object_link'><a href="Rubu.html" title="Rubu (module)">Rubu</a></span> itself. For example if user wants
to see all executed command, then “verbose” option should be selected.</p>
<p><strong>Var</strong> is used to control how <strong>Steps</strong> behave
and also details of <strong>Move</strong> internals. <strong>Info</strong>
is meant for runtime generated information. The division is semantic and
@@ -205,31 +206,31 @@
example.</p>
<p>To summarize and highlight the relationships between concepts, see the
diagram below:</p>
-<pre class="code ruby"><code class="ruby">RBP => Trial+ => Step+ [s/p] => Move+ [s/p] => Source*, Target*
+<pre class="code ruby"><code class="ruby">RBP => Trail+ => Step+ [s/p] => Move+ [s/p] => SourceMark*, TargetMark*
=> Order+
=> Var*
=> Info*
* = Zero or more
+ = One or more
s = Serial
p = Parallel</code></pre>
-<p>RBP includes <strong>Trials</strong>, <strong>Orders</strong>, and possibly
-<strong>Vars</strong> and <strong>Infos</strong>. <strong>Trial</strong>
+<p>RBP includes <strong>Trails</strong>, <strong>Orders</strong>, and possibly
+<strong>Vars</strong> and <strong>Infos</strong>. <strong>Trail</strong>
includes one or more <strong>Steps</strong>, which can be executed in
sequence or in parallel.</p>
<p><strong>Step</strong> includes one or more <strong>Moves</strong>, and they
can also be sequential or parallel. <strong>Move</strong> has typically at
-least one <strong>Source</strong> and at least one <strong>Target</strong>.
-However, there are exceptions as well.</p>
+least one <strong>SourceMark</strong> and at least one
+<strong>TargetMark</strong>. However, there are exceptions as well.</p>
-<p>The suggested ordering within <span class='object_link'><a href="Rubu.html" title="Rubu (class)">Rubu</a></span> Build Program is:</p>
+<p>The suggested ordering within <span class='object_link'><a href="Rubu.html" title="Rubu (module)">Rubu</a></span> Build Program is:</p>
<dl class="rdoc-list label-list"><dt>configuration
<dd>
<p>Process command line arguments and assign options that are used to control
the build process.</p>
</dd><dt>file collection
@@ -252,11 +253,11 @@
execute.</p>
</dd></dl>
<h2 id="label-Configuration">Configuration</h2>
-<p><strong>Order</strong> space default are set by the <span class='object_link'><a href="Rubu.html" title="Rubu (class)">Rubu</a></span> library and user
+<p><strong>Order</strong> space default are set by the <span class='object_link'><a href="Rubu.html" title="Rubu (module)">Rubu</a></span> library and user
can override the default based on command line parameters if needed.</p>
<p>Set default values for <strong>Var</strong> space. After default setting,
override the defaults with possible control from command line arguments.</p>
@@ -286,11 +287,11 @@
also the “basename” of the file is changed. This is achieved by giving the
“peer” method a third argument specifying the new “basename”.</p>
<h2 id="label-Step+definition">Step definition</h2>
-<p><strong>Step</strong> is defined by inheriting of the <span class='object_link'><a href="Rubu.html" title="Rubu (class)">Rubu</a></span>
+<p><strong>Step</strong> is defined by inheriting of the <span class='object_link'><a href="Rubu.html" title="Rubu (module)">Rubu</a></span>
<strong>Step</strong> classes and defining the custom “step” method. If a
specific setup for the <strong>Step</strong> is required, then an
additional “setup” method can be defined as well.</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>CleanUp</span> <span class='op'><</span> <span class='const'>StepAlways</span>
@@ -300,11 +301,11 @@
<span class='kw'>end</span>
</code></pre>
<p>“setup” method is typically used to change the command according to user
configuration. “step” method is the action for <strong>Step</strong>.
-<span class='object_link'><a href="Rubu.html" title="Rubu (class)">Rubu</a></span> executes it, if necessary. For example, if <strong>Step</strong> is
+<span class='object_link'><a href="Rubu.html" title="Rubu (module)">Rubu</a></span> executes it, if necessary. For example, if <strong>Step</strong> is
a <strong>StepAged</strong> class, then the “step” method is only called if
the source <strong>Mark</strong> is newer than the target
<strong>Mark</strong>.</p>
<p>“step” method may include only one command or a set of commands. If one
@@ -376,11 +377,11 @@
<pre class="code ruby"><code class="ruby"><span class='const'>Trail</span><span class='period'>.</span><span class='id identifier rubyid_run'>run</span><span class='lparen'>(</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>default</span><span class='tstring_end'>'</span></span> <span class='rparen'>)</span>
</code></pre>
<h2 id="label-Final+notes">Final notes</h2>
-<p><span class='object_link'><a href="Rubu.html" title="Rubu (class)">Rubu</a></span> treats single <strong>Mark</strong> objects and Array of
+<p><span class='object_link'><a href="Rubu.html" title="Rubu (module)">Rubu</a></span> treats single <strong>Mark</strong> objects and Array of
<strong>Mark</strong> objects the “same” way. In practice this means that
the most common methods for <strong>Mark</strong> objects are implemented
for Array as well. Hence, you can call a <strong>Mark</strong> method for
an Array, and they will actually be applied for each individual
<strong>Mark</strong> in the collection.</p>
@@ -394,10 +395,10 @@
<p>For this version, example is the testcase.</p>
</div></div>
<div id="footer">
- Generated on Thu Aug 30 16:05:51 2018 by
+ Generated on Fri Aug 31 09:32:06 2018 by
<a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
0.8.7.6 (ruby-2.3.3).
</div>
</body>
\ No newline at end of file