[llvm-commits] [llvm-top] r40237 - /llvm-top/trunk/README.txt

[Reid Spencer]

Author: reid
Date: Sat Jul 21 01:10:43 2007
New Revision: 40237

URL: http://llvm.org/viewvc/llvm-project?rev=40237&view=rev
Log:
Document how to use llvm-top and make other minor corrections.

Modified:
    llvm-top/trunk/README.txt

Modified: llvm-top/trunk/README.txt
URL: http://llvm.org/viewvc/llvm-project/llvm-top/trunk/README.txt?rev=40237&r1=40236&r2=40237&view=diff

==============================================================================
--- llvm-top/trunk/README.txt (original)
+++ llvm-top/trunk/README.txt Sat Jul 21 01:10:43 2007
@@ -4,42 +4,113 @@
 You are reading the README for the llvm-top module of the LLVM project. This
 module should be the first thing you check out when accessing the LLVM
 project's subversion repository. From here all other modules are accessible
-via the makefile.
+via small scripts.
 
 You should check this module out with the following subversion command:
 
    svn co http://llvm.org/svn/llvm-project/llvm-top/trunk llvm-top
 
-Once you've done that, you can then check out a module (and all its
-dependencies) with the get script located here. For example:
+Alternatively, if you have commit access, use this form:
+
+   svn co https://username@llvm.org/svn/llvm-project/llvm-top/trunk llvm-top
+
+Once you've checked out llvm-top, you can then check out a module (and all its
+dependencies) with the "get" script located here. For example:
 
   ./get llvm-gcc-4-0
 
 which will check out both llvm and llvm-gcc-4-0 because the latter depends on
 the former.
 
-Similarly you can build any module just by using the build script located
-here. For example:
+In addition to checking out software, there are scripts to build, install, and
+clean the modules. They have the obvious names. These scripts do not dictate
+how to build, install or clean the modules; that is up to the module. The 
+only thing these scripts depend on is a file named ModuleInfo.txt located in
+each module's top directory. This module can have the following definitions:
+
+  DepModule:  - the list of modules this module depends on 
+  BuildCmd:   - a command to build (and configure) the module
+  InstallCmd: - a command to install the module
+  CleanCmd:   - a command to clean the module
+
+The scripts in llvm-top determine dependencies based on the DepModule lines of
+the various modules. This is how it knows which modules need to be checked out
+and what order to build them in. The three definitions ending in "Cmd" specify
+commands to be run. They are used by the build, install and clean scripts,
+respectively. Modules are free to specify whatever command is appropriate to
+build, install or clean that module.
+
+Each of these scripts uses a common library of shell functions (library.sh) to
+ensure their function is regular. In particular, they all accept the same set 
+of arguments. The arguments recognized are listed below in the order they
+are recognized by the scripts:
+
+  VEROBSE={verbosity_level}
+     This controls how verbose the scripts are in their output. The default
+     level is 0 which produces no output unless there's an error. At level 1
+     you'll get basic confirmation of the action taken. At level 2 you'll get
+     a dialogue of the individual steps taken by the script and verbose 
+     output from anything it runs.  At level 3 you'll get full diagnostics
+     messages (generally only useful for implementers of these scripts).
+
+  PREFIX=/path/to/install/directory
+     This is the prefix directory for installation. It is the expected final
+     location for installation of the software.
+
+  DESTDIR=/path/to/destination/directory
+     Specify the directory above where the install prefix will install. This
+     is handy for package maintainers. You can set PREFIX=/usr/bin but then
+     you don't actually want it installed there! So, specify DESTDIR=/tmp and
+     it would actually get installed in /tmp/usr/bin.
+
+  MODULE={module_name}
+     This allows you to override the name of the module (not recommended).
+
+  LLVM_TOP=/path/to/llvm-top
+     This allows you to override the location of the llvm-top directory.
+     
+  -*
+  --*
+  *=*
+     Any options matching these patterns are collected and passed down to the
+     build, install or clean commands.
+
+  [a-zA-Z]*
+     Any option not matching something above and starting with a letter 
+     specifies a module name to work on.
+
+  *
+     Anything else is an error.
+
+So, for example:
 
   ./build llvm-gcc-4-0 ENABLE_OPTIMIZED=1 PREFIX=/my/install/dir VERBOSE=1
 
 As you might guess, this will check out both llvm and llvm-gcc-4-0 if they
-haven't been and then configure and build them according to the arguments 
-that you specified. 
+haven't been and then configure and build optimized versions of each. They
+will be configured to install to /my/install/dir and there will be some
+minimal confirmation of the steps taken.
 
 The modules available are:
 
   llvm-top     - This directory
+  sample       - A sample module you can use as a template for your own
+  support      - The support libraries, makefile system, etc.
   llvm         - The core llvm software
+  llvm-gcc-4.0 - The C/C++/Obj-C front end for llvm, based on GCC 4.0
+  llvm-gcc-4.2 - The C/C++/Obj-C front end for llvm, based on GCC 4.2
   cfe          - The new C/C++/Obj-C front end for llvm
-  llvm-gcc-4-0 - The C/C++/Obj-C front end for llvm, based on GCC 4.0
-  llvm-gcc-4-2 - The C/C++/Obj-C front end for llvm, based on GCC 4.2
   test-suite   - The llvm test suite
   stacker      - The stacker front end (a 'Forth-like' language)
   hlvm         - High Level Virtual Machine (nascent)
   java         - Java Front End (unfinished, out of date)
+  poolalloc    - The pooled allocator from Chris Lattner's thesis
+
+
+You can check out any number of modules using the "get" script, for example,
+like this:
 
-You can check out any number of modules using the "get" script.
+  ./get llvm-gcc-4.0 test-suite stacker
 
 -----------------------------------------------------------------------------