[llvm-commits] [hlvm] r38146 - /hlvm/trunk/docs/DevelopersGuide.html
Reid Spencer
reid at x10sys.com
Sat Jul 7 17:00:26 PDT 2007
Author: reid
Date: Sat Jul 7 19:00:26 2007
New Revision: 38146
URL: http://llvm.org/viewvc/llvm-project?rev=38146&view=rev
Log:
Add information about the usage of scons and the various builder rules.
Modified:
hlvm/trunk/docs/DevelopersGuide.html
Modified: hlvm/trunk/docs/DevelopersGuide.html
URL: http://llvm.org/viewvc/llvm-project/hlvm/trunk/docs/DevelopersGuide.html?rev=38146&r1=38145&r2=38146&view=diff
==============================================================================
--- hlvm/trunk/docs/DevelopersGuide.html (original)
+++ hlvm/trunk/docs/DevelopersGuide.html Sat Jul 7 19:00:26 2007
@@ -17,6 +17,13 @@
<li><a href="#patches">Patches</a></li>
</ol>
</li>
+ <li><a href="#build">Build System</a></li>
+ <ol>
+ <li><a href="#scons">About SCONS</a></li>
+ <li><a href="#config">Configuring</a></li>
+ <li><a href="#rules">Build Rules</a></li>
+ </ol>
+ </li>
<li><a href="#style">Coding Style</a></li>
<li><a href="#appendices">Appendices</a>
<ol>
@@ -35,7 +42,7 @@
<div class="text">
<p>This document is a manual for developers who wish to contribute to the HLVM
project. It covers topics such as copyright assignment, license, coding style,
- and project rules.</p>
+ the build system and project rules.</p>
</div>
<!-- *********************************************************************** -->
@@ -118,6 +125,258 @@
</div>
<!-- ======================================================================= -->
+<div class="section"><a name="build">Build System</a></div>
+<div class="text">
+ <p>This section describes the HLVM build system.</p>
+</div>
+
+<!-- ======================================================================= -->
+<div class="subsection"><a name="scons">About SCONS</a></div>
+<div class="text">
+ <p>The HLVM project uses the <a href="http://www.scons.org/">scons</a>
+ software construction tool to orchestrate its builds. This gives us superior
+ dependency checking and a much more flexible tool for developing the build
+ system. We started with "make" but were convinced of SCons superiority after
+ trying it for a week. If you're not familiar with it, please read up on it
+ and get a general understanding. You don't need detailed understanding because
+ all you will most likely need to do is follow the instructions in this
+ section.</p>
+</div>
+
+<!-- ======================================================================= -->
+<div class="subsection"><a name="config">Configuring</a></div>
+<div class="text">
+ <h3>Configuration On Every Build</h3>
+ <p>Unlike some other build systems (e.g. autoconf/automake), the
+ configuration and construction phases of building are not separated with
+ scons. The configuration parameters are checked every time you build. While
+ you might think that will slow things down, it doesn't. The configuration
+ information is cached and proceeds quite quickly once your configuration is
+ stable. If something changes in your environment, only those pieces affected
+ will get re-configured. This saves a lot of time and hassle by telling you of
+ any configuration errors on the very next build.</p>
+ <h3>The Options Cache</h3>
+ <p>Configuration parameters are specified on the scons command line. The
+ values of these parameters are stored in the <i>options cache</i> which is
+ simply a file named .options_cache in the root source directory. If the file
+ doesn't exist, it will be created the first time you run scons. On subsequent
+ runs, the values are loaded from this cache and used unless new values are
+ given on the command line. In this way, you only need to specify your options
+ once and then they "stick" from that point forward.</p>
+ <h3>Configuration Options</h3>
+ <p>HLVM has a variety of options to assist with configuring HLVM for your
+ environment and build choices. Each option has a default that will work in
+ many environments but might need adjusting for your environment. The default
+ assumes various software packages are in <tt>/usr/local</tt> and that a fully
+ debuggable version of HLVM should be built. The table below provides the
+ full list of options.</p>
+ <table>
+ <tr><th>Option</th><th>Description</th><th>Default</th></tr>
+ <tr>
+ <td>assertions</td>
+ <td>Include assertions in the code. This can be enabled or disabled separate
+ from the setting for debug.</td>
+ <td>1</td></tr>
+ <tr>
+ <td>debug</td>
+ <td>Build with debug options turned on. This includes #ifdef/#endif code as
+ well as instructing the compiler to include debug information (-g)</td>
+ <td>1</td></tr>
+ <tr>
+ <td>inline</td>
+ <td>Cause inline code to be inline. This causes inline functions to really
+ be inline. Its off by default for better debuggability.</td><td>0</td>
+ </tr>
+ <tr>
+ <td>optimize</td>
+ <td>Build object files with optimization. This turns on compiler
+ optimization (-O3) to make the code efficient.</td><td>0</td></tr>
+ <tr>
+ <td>profile</td>
+ <td>Generate profiling aware code. This causes the compiler to construct the
+ code so that it can be profiled (-pg on Unix).</td><td>0</td></tr>
+ <tr>
+ <td>small</td>
+ <td>Generate smaller code rather than faster. Instructs the code to favor
+ smaller object files and executables than faster ones. Might be useful for
+ memory constrained platforms.</td>
+ <td>0</td></tr>
+ <tr>
+ <td>prefix</td>
+ <td>Specify where to install HLVM. This is the root directory of where HLVM
+ will be installed when you run <tt>scons install</tt></td>
+ <td>/usr/local</td></tr>
+ <tr>
+ <td>confpath</td>
+ <td>Specify additional configuration dirs to search. This is a unix style
+ path (colon separate) of directories to include in the search for software
+ packages. These directories will be searched first. If you put your
+ software in a non-standard place like /proj (Reid) or /more (Saem) then
+ you'll want to use this option.</td>
+ <td>{empty}</td></tr>
+ <tr>
+ <td>with_llvm</td>
+ <td>Specify where LLVM is installed.</td>
+ <td>/usr/local</td></tr>
+ <tr>
+ <td>with_apr</td>
+ <td>Specify where apr is installed.</td>
+ <td>/usr/local/apr</td></tr>
+ <tr>
+ <td>with_apru</td>
+ <td>Specify where apr-utils is installed.</td>
+ <td>/usr/local/apr</td></tr>
+ <tr>
+ <td>with_xml2</td>
+ <td>Specify where LibXml2 is installed.</td>
+ <td>/usr/local</td></tr>
+ <tr>
+ <td>with_gperf</td>
+ <td>Specify where the gperf program is installed.</td>
+ <td>/usr/local/bin/gperf</td></tr>
+ <tr>
+ <td>with_llc</td>
+ <td>Specify where the LLVM compiler is installed.</td>
+ <td>/usr/local/bin/llc</td></tr>
+ <tr>
+ <td>with_llvmdis</td>
+ <td>Specify where the LLVM disassembler is installed.</td>
+ <td>/usr/local/bin/llvm-dis</td></tr>
+ <tr>
+ <td>with_llvmas</td>
+ <td>Specify where the LLVM assembler is installed.</td>
+ <td>/usr/local/bin/llvm-as</td></tr>
+ <tr>
+ <td>with_llvmgcc</td>
+ <td>Specify where the LLVM C compiler is installed.</td>
+ <td>/usr/local/bin/llvm-gcc</td></tr>
+ <tr>
+ <td>with_llvmgxx</td>
+ <td>Specify where the LLVM C++ compiler is installed.</td>
+ <td>/usr/local/bin/llvm-g++</td></tr>
+ <tr>
+ <td>with_llvmar</td>
+ <td>Specify where the LLVM bytecode archiver is installed.</td>
+ <td>/usr/local/bin/llvm-g++</td></tr>
+ <tr>
+ <td>with_llvm2cpp</td>
+ <td>Specify where the LLVM llvm2cpp program is installed.</td>
+ <td>/usr/local/bin/llvm2cpp</td></tr>
+ <tr>
+ <td>with_runtest</td>
+ <td>Specify where DejaGnu runtest program is installed.</td>
+ <td>/usr/local/bin/runtest</td></tr>
+ <tr>
+ <td>with_doxygen</td>
+ <td>Specify where the doxygen program is installed.</td>
+ <td>/usr/local/bin/doxygen</td></tr>
+ <tr>
+ <td>with_xsltproc</td>
+ <td>Specify where the XSLT processor is installed.</td>
+ <td>/usr/local/bin/xsltproc</td>
+ </tr>
+ </table>
+ <h3>Configuration Prompts</h3>
+ <p>When you first run <tt>scons</tt> against HLVM, if you did not specify the
+ <tt>confpath</tt> option or the configuration code cannot otherwise find a
+ package it needs, you will be prompted to enter the applicable path names
+ manually. You only need to do this once as the values you enter will be
+ remembered in the <tt>.options_cache</tt> file. These prompts will repeat
+ until you enter a path in which the package is properly recognized. If you
+ wish to abort this, just enter <tt>exit</tt> or <tt>quit</tt> at any prompt.
+ </p>
+</div>
+
+<!-- ======================================================================= -->
+<div class="subsection"><a name="rules">Build Rules</a></div>
+<div class="text">
+ <p>This subsection describes the various build rules and extensions to SCons
+ that HLVM uses.</p>
+ <h3>The <tt>build</tt> python module</h3>
+ <p>For convenience, and to unclutter the SConscript files, the top level
+ <tt>build</tt> directory contains a python module that provides the build
+ facilities for HLVM. This module manipulates an SCons environment to set the
+ variables and define the builder rules for HLVM. The public interface to this
+ library is in the <tt>hlvm.py</tt> module. No other module should be imported
+ into the SConscript files.</p>
+ <h3>HLVM Builder Rules</h3>
+ <p>HLVM requires some specialized build rules beyond what SCons provides.
+ While general construction of static libraries, shared libraries, and
+ executables use the standard SCons builders, several more are defined in the
+ <tt>build</tt> python module. The table below describes the HLVM specific
+ builders.</p>
+ <table>
+ <tr><th>Builder</th><th>Source</th><th>Target</th><th>Description</th></tr>
+ <tr>
+ <td>RNGTokenizer</td>
+ <td>Relax/NG Schema (.rng)</td>
+ <td>*Tokenizer.h, *Tokenizer.cpp, *TokenHash.cpp</td>
+ <td>This builder scans a Relax/NG Schema for element, attribute, and
+ enumerated value names. It then uses these tokens to build a perfect
+ hash function (via <tt>gperf</tt>) for quickly recognizing the tokens
+ and converting it to an enumeration value. This is provided to make
+ recognizing the element and attributes names of an XML document faster.
+ </td>
+ </tr>
+ <tr>
+ <td>RNGQuoteSource</td>
+ <td>Relax/NG Schema (.rng)</td>
+ <td>C++ Strings For Inclusion (.inc)</td>
+ <td>This builder converts a Relax/NG schema into a set of strings that can
+ be #included into a C++ program as a literal string. It strips out
+ comments, annotations, and converts special characters into the C++
+ equivalent. The purpose here is to allow a single source for the schema
+ to be incorporated directly into the software so that no file I/O is
+ necessaroy to access the schema.</td>
+ </tr>
+ <tr>
+ <td>Bytecode</td>
+ <td>C++ Source (.cpp)</td>
+ <td>LLVM Bytecode (.bc)</td>
+ <td>This builder compiles a C++ source file and produces an equivalent
+ LLVM bytecode file. This allows us to incorporate C++ source into the
+ Runtime as linkable bytecode.</td>
+ </tr>
+ <tr>
+ <td>BytecodeArchive</td>
+ <td>LLVM Bytecode (.bc)</td>
+ <td>LLVM Bytecode Archive (.bca)</td>
+ <td>This builder collects a group of LLVM Bytecode files together and
+ creates a bytecode archive from them using <tt>llvm-ar</tt></td>
+ </tr>
+ <tr>
+ <td>Cpp2LLVMCpp</td>
+ <td>C++ Source (.cxx)</td>
+ <td>C++ Source (.cpp)</td>
+ <td>This builder uses the <tt>llvm2cpp</tt> to turn source C++ into
+ equivalent C++ calls against the LLVM Intermediate Representation (IR)
+ to construct the same program or program fragment. The construction
+ environment variable LLVM2CPPFLAGS can be set to control what options
+ are passed to <tt>llvm2cpp</tt>. See the <tt>llvm2cpp</tt> manual page
+ for details. Examples are in the <tt>hlvm/CodeGen/SConscript</tt>
+ file.</td>
+ </tr>
+ <tr>
+ <td>Check</td>
+ <td>n/a</td>
+ <td>n/a</td>
+ <td>This builder is a little special. It is used to run the DejaGnu test
+ suite. It is aliased on the command line as the target "check" so that
+ the <tt>scons check</tt> command will invoke this build.</td>
+ </tr>
+ <tr>
+ <td>Doxygen</td>
+ <td>n/a</td>
+ <td>doxygen.tar.gz</td>
+ <td>This builder runs the doxygen documentation generator on the source
+ code and builds a gzipped tar file containing doxygen's output. This
+ allows the HLVM API documentation, generated from source code comments,
+ to be packged into a single file.</td>
+ </tr>
+ </table>
+</div>
+
+<!-- ======================================================================= -->
<div class="section"><a name="style">Coding Style</a></div>
<div class="text">
<p>Contributions to HLVM must meet the following Coding Style
@@ -130,7 +389,8 @@
written in C++. We know this isn't the greatest language in the world, but
it is the most compatible for meeting HLVM's integration and platform
support requirements.</li>
- <li>Utility programs should be written in Perl</li>
+ <li>Utility programs should be written in python, especially if they are
+ build related.</li>
<li>Files must not exceed 80 columns in width</li>
<li>Indentation is 2 spaces (no tabs).</li>
</ul>
More information about the llvm-commits
mailing list