doc/index.html in rubu-0.0.1 vs doc/index.html in rubu-0.0.2

- old
+ new

@@ -67,29 +67,29 @@ <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 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 are fairly fixed. +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 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> <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 likely to happen when the user needs many exceptions to basic rules, also -when other tasks than just build task are needed.</p> +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 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> -<h2 id="label-Concepts">Concepts</h2> +<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: +“Example” chapter below). However for longer term the main concepts are +important as well (See: “Concepts” chapter below).</p> -<p>TBD</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> <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> @@ -97,11 +97,11 @@ <p>It builds a “hello world” type program which is split into two C source files. The main file is hand written and the other file is generated with a script. File generation is part of the build program.</p> -<p>Various executions of the build is captured in:</p> +<p>Different execution variations of the build program is captured 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_runme'>runme</span> </code></pre> <p>Please see example executions within the script and run the script in the @@ -109,23 +109,270 @@ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_cd'>cd</span> <span class='id identifier rubyid_example'>example</span> <span class='id identifier rubyid_runme'>runme</span> </code></pre> -<p>Also take a look into the build program:</p> +<p>Also take a look into the build program itself:</p> <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> +<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. +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&#39;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 +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 +target file(s). For example, a C source file compilation is a +<strong>Step</strong> where one source file is converted to a corresponding +object file. <strong>Step</strong> is given source <strong>Mark</strong> +and target <strong>Mark</strong> as arguments. Hence this type of +<strong>Step</strong> a is one-to-one mapping.</p> + +<p>Linking multiple objects to an executable is a many-to-one mapping. This is +performed by a <strong>Step</strong> where there are multiple sources and +one target, i.e. objects and the executable respectively.</p> + +<p><strong>Step</strong> class (or object) has “step” method which includes +the <strong>Move</strong> that is needed to create the target. +<strong>Move</strong> is either a Shell or a Ruby command. +<strong>Move</strong> is executed only if necessary. Typically the +<strong>Step</strong> is sensitive to source being newer that the target, +just as with Make and Rake. However, it is possible to have a +<strong>Step</strong> that is sensitive to file content, for example. +Timestamp might change, but if the content is the same as previously, no +<strong>Move</strong> is made.</p> + +<p><strong>Step</strong> is typically a simple command. In some cases +<strong>Step</strong> can include multiple <strong>Moves</strong>. These +can be performed in sequence or in parallel, with a multicore CPU.</p> + +<p><strong>Trail</strong> is a collection of <strong>Steps</strong>. +<strong>Trail</strong> has a name, and it can be references by another +<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 +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>, +<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 +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 +user might choose to combine everything to <strong>Var</strong> space, for +example.</p> + +<p>To summarize and highlight the relationships between concepts, see the +diagram below:</p> + +<pre class="code ruby"><code class="ruby">RBP =&gt; Trial+ =&gt; Step+ [s/p] =&gt; Move+ [s/p] =&gt; Source*, Target* + =&gt; Order+ + =&gt; Var* + =&gt; 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> +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> + +<p>The suggested ordering within <span class='object_link'><a href="Rubu.html" title="Rubu (class)">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 +<dd> +<p>Collect source and target files either using Ruby with glob pattern, direct +references, or through manifest files. Convert file names to +<strong>Mark</strong> objects.</p> +</dd><dt>step definition +<dd> +<p>Define <strong>Steps</strong>. Inherit one of the <strong>Step</strong> +types (classes) and define at least the “step” method.</p> +</dd><dt>trail definition +<dd> +<p>Define <strong>Trails</strong>. Create all possible flows that user wants +to execute. Use hierarchy for your benefit in order to make RBP maintenance +as light as possible.</p> +</dd><dt>trail selection +<dd> +<p>Find the selected <strong>Trail</strong> or <strong>Trails</strong> and +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 +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> + +<p>Finally setup <strong>Trails</strong> by calling:</p> + +<pre class="code ruby"><code class="ruby"><span class='const'>Trail</span><span class='period'>.</span><span class='id identifier rubyid_setup'>setup</span> +</code></pre> + +<h2 id="label-File+collection">File collection</h2> + +<p>If the build environment has clear and clean directory structure, it is +typically easiest to collect files programmatically. For example, to get +all C source files:</p> + +<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_cee_files'>cee_files</span> <span class='op'>=</span> <span class='const'>Mark</span><span class='period'>.</span><span class='id identifier rubyid_glob'>glob</span><span class='lparen'>(</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='embexpr_beg'>#{</span><span class='const'>Var</span><span class='lbracket'>[</span><span class='symbol'>:source_dir</span><span class='rbracket'>]</span><span class='embexpr_end'>}</span><span class='tstring_content'>/*.c</span><span class='tstring_end'>&quot;</span></span> <span class='rparen'>)</span> +</code></pre> + +<p>This creates a list of <strong>Mark</strong> objects which are source +files. The corresponding object files can be created with “peer” method:</p> + +<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_obj_files'>obj_files</span> <span class='op'>=</span> <span class='id identifier rubyid_cee_files'>cee_files</span><span class='period'>.</span><span class='id identifier rubyid_peer'>peer</span><span class='lparen'>(</span> <span class='const'>Var</span><span class='lbracket'>[</span> <span class='symbol'>:build_dir</span> <span class='rbracket'>]</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>.o</span><span class='tstring_end'>&#39;</span></span> <span class='rparen'>)</span> +</code></pre> + +<p>This method invocation takes an Array of <strong>Mark</strong> objects and +calls “peer” method for them. “peer” method changes the directory and +extension, and returns a new <strong>Mark</strong> object. In some cases +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> +<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'>&lt;</span> <span class='const'>StepAlways</span> + <span class='kw'>def</span> <span class='id identifier rubyid_step'>step</span> + <span class='id identifier rubyid_shrun'>shrun</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>rm -f </span><span class='embexpr_beg'>#{</span><span class='const'>Var</span><span class='lbracket'>[</span> <span class='symbol'>:build_dir</span> <span class='rbracket'>]</span><span class='embexpr_end'>}</span><span class='tstring_content'>/*.o</span><span class='tstring_end'>&quot;</span></span> + <span class='kw'>end</span> +<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 +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 +command is needed, it can be simply executed:</p> + +<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_step'>step</span> + <span class='id identifier rubyid_shrun'>shrun</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>rm -f </span><span class='embexpr_beg'>#{</span><span class='const'>Var</span><span class='lbracket'>[</span> <span class='symbol'>:build_dir</span> <span class='rbracket'>]</span><span class='embexpr_end'>}</span><span class='tstring_content'>/*.o</span><span class='tstring_end'>&quot;</span></span> +<span class='kw'>end</span> +</code></pre> + +<p>If there are multiple commands, then the commands can be grouped for +sequential (“walk”) or parallel execution (“fork”).</p> + +<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_step'>step</span> + <span class='id identifier rubyid_fork'>fork</span> <span class='kw'>do</span> + <span class='id identifier rubyid_shuse'>shuse</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>rm -f </span><span class='embexpr_beg'>#{</span><span class='const'>Info</span><span class='lbracket'>[</span> <span class='symbol'>:gen_files</span> <span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_rpath'>rpath</span><span class='embexpr_end'>}</span><span class='tstring_end'>&quot;</span></span> + <span class='id identifier rubyid_shuse'>shuse</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>rm -f </span><span class='embexpr_beg'>#{</span><span class='const'>Var</span><span class='lbracket'>[</span> <span class='symbol'>:build_dir</span> <span class='rbracket'>]</span><span class='embexpr_end'>}</span><span class='tstring_content'>/*.o</span><span class='tstring_end'>&quot;</span></span> + <span class='kw'>end</span> +<span class='kw'>end</span> +</code></pre> + +<p>Note that the commands are defined with “shuse”. The logic is that we +don&#39;t execute the commands right away as in “shrun”. Instead we just +register the commands to the group. When the group definition is closed +(“end” keyword), it is complete, and we execute it either sequentially or +in parallel.</p> + +<h2 id="label-Trail+definition">Trail definition</h2> + +<p><strong>Trail</strong> is a collection of <strong>Steps</strong> or other +<strong>Trails</strong>, or a mix of both. For example, in order to compile +a set of C source files to object files, we might define:</p> + +<pre class="code ruby"><code class="ruby"><span class='const'>Fork</span><span class='period'>.</span><span class='id identifier rubyid_form'>form</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>compile-cee</span><span class='tstring_end'>&#39;</span></span> <span class='kw'>do</span> + <span class='const'>GccCompileFile</span><span class='period'>.</span><span class='id identifier rubyid_usezip'>usezip</span><span class='lparen'>(</span> <span class='id identifier rubyid_cee_files'>cee_files</span><span class='comma'>,</span> <span class='id identifier rubyid_obj_files'>obj_files</span> <span class='rparen'>)</span> +<span class='kw'>end</span> +</code></pre> + +<p>This creates a parallel (“Fork”) <strong>Trail</strong> called +“compile-cee”. Collection of <strong>Steps</strong> is created with +“usezip” method. “usezip” performs two operations: it creates a zip type +mix of “cee_files” and “obj_files”. The “zip” method of Ruby Array is used. +“zip” creates an Array of <strong>Mark</strong> pairs. Each pair is passed +to a “GccCompileFile” <strong>Step</strong> object. Finally we have a +collection of <strong>Steps</strong> which are executed in parallel when +“compile-cee” is invoked.</p> + +<p>Here the defined <strong>Trail</strong> from above is referenced in order +to create a <strong>Trail</strong> for the complete compile flow:</p> + +<pre class="code ruby"><code class="ruby"><span class='const'>Walk</span><span class='period'>.</span><span class='id identifier rubyid_form'>form</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>default</span><span class='tstring_end'>&#39;</span></span> <span class='kw'>do</span> + <span class='id identifier rubyid_pick'>pick</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>compile-cee</span><span class='tstring_end'>&#39;</span></span> + <span class='const'>GccLinkExe</span><span class='period'>.</span><span class='id identifier rubyid_use'>use</span><span class='lparen'>(</span> <span class='id identifier rubyid_obj_files'>obj_files</span><span class='comma'>,</span> <span class='id identifier rubyid_exe_file'>exe_file</span> <span class='rparen'>)</span> +<span class='kw'>end</span> +</code></pre> + +<p>This <strong>Trail</strong> definition defines that we want to first +execute “compile-cee” and then a <strong>Step</strong> which will create an +executable from object file collection. “GccLinkExe” <strong>Step</strong> +is called with “use” method, which will register the <strong>Step</strong> +to the enclosing <strong>Trail</strong>, “default”.</p> + +<h2 id="label-Trail+selection">Trail selection</h2> + +<p>The final stage in RBP execution is to use command line control for +selecting the executed <strong>Trails</strong> and then execute them. The +above definition (from previous section) is executed with:</p> + +<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'>&#39;</span><span class='tstring_content'>default</span><span class='tstring_end'>&#39;</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 +<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> + +<p><strong>Step</strong> has sources and targets. Even if a step has only one +source and one target, the actual container is an Array. If you want to +refer to the source, i.e. the only existing source, you can use the +“source” method. Same applies to targets (i.e. use the “target” method).</p> + <h2 id="label-Testing">Testing</h2> <p>For this version, example is the testcase.</p> </div></div> <div id="footer"> - Generated on Fri Jun 29 10:04:07 2018 by + Generated on Sun Jul 1 17:48:17 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