Adding a web page on how to start a new LLVM Project.

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@7095 91177308-0d34-0410-b5e6-96231b3b80d8
author: John Criswell <criswell@uiuc.edu> 2003-07-03 15:37:52 +0000
committer: John Criswell <criswell@uiuc.edu> 2003-07-03 15:37:52 +0000
commit: f2413aedb6aca58dc690d81095193307a8df46ff (patch)
tree: 36ddcd3300ea18504a9267f7c76ec8d918c7fd7e /docs/Projects.html
parent: 5bfccb9defee2026e113c1fd694eb29b99d4f8a6 (diff)
download: llvm-f2413aedb6aca58dc690d81095193307a8df46ff.tar.gz
llvm-f2413aedb6aca58dc690d81095193307a8df46ff.tar.bz2
llvm-f2413aedb6aca58dc690d81095193307a8df46ff.tar.xz
1 files changed, 221 insertions, 0 deletions
diff --git a/docs/Projects.html b/docs/Projects.html
new file mode 100644
index 0000000000..2debb6f7be
--- /dev/null
+++ b/docs/Projects.html
@@ -0,0 +1,221 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+	<head>
+		<title>Creating an LLVM Project</title>
+	</head>
+
+	<body bgcolor=white>
+
+	<center><h1>Creating an LLVM Project<br></h1></center>
+
+	<!--===============================================================-->
+	<h2><a name="a">Overview</a><hr></h2>
+	<!--===============================================================-->
+
+	In order to set up a new project that uses the LLVM build system,
+	libraries, and header files, follow these steps:
+
+	<ol>
+		<li>
+		Copy the <tt>llvm/projects/sample</tt> directory to any place
+		of your choosing.  You can place it anywhere you like, although
+		someplace underneath your home directory would work best.
+		<p>
+
+		<li>
+		Edit the <tt>Makefile.config</tt> and <tt>Makefile.common</tt>
+		files so that the LLVM_SRC_ROOT variable equals the absolute
+		pathname of the LLVM source tree and LLVM_OBJ_ROOT equals the
+		pathname of where LLVM was built.
+
+		<p>
+
+		For example, if the LLVM source tree is in
+		<tt>/usr/home/joe/src/llvm</tt>, and you configured it with
+		<tt>--with-objroot=/tmp</tt> when his home directory is
+		<tt>/usr/home/joe</tt>, then
+		LLVM_SRC_ROOT=<tt>/usr/home/joe/src/llvm</tt> and
+		LLVM_OBJ_ROOT=<tt>/tmp/src/llvm</tt>.
+		<p>
+
+		<li>
+		Add your source code to the source tree.
+		<p>
+
+		<li>
+		Modify the various Makefiles to contain the names of the
+		objects that you want to build.
+	</ol>
+
+	<!--===============================================================-->
+	<h2><a name="Source Tree Layout">Source Tree Layout</a><hr></h2>
+	<!--===============================================================-->
+
+	In order to use the LLVM build system, you will want to lay out your
+	source code so that it can benefit from the build system's features.
+	Mainly, you want your source tree layout to look similar to the LLVM
+	source tree layout.  The best way to do this is to just copy the
+	project tree from <tt>llvm/projects/sample</tt> and modify it to meet
+	your needs, but you can certainly add to it if you want.
+
+	Underneath your top level directory, you should have the following
+	directories:
+
+	<dl compact>
+		<dt><b>lib</b>
+		<dd>
+		This subdirectory should contain all of your library source
+		code.  For each library that you build, you will have one
+		directory in <b>lib</b> that will contain that library's source
+		code.
+
+		<p>
+		Libraries can be object files, archives, or dynamic libraries.
+		The <b>lib</b> directory is just a good place for these as it
+		places them all in a directory from which they can be linked
+		later on.
+
+		<dt><b>include</b>
+		<dd>
+		This subdirectory should contain any header files that are
+		global to your project.  By global, we mean that they are used
+		by more than one library or executable of your project.
+		<p>
+		By placing your header files in <b>include</b>, they will be
+		found automatically by the LLVM build system.  For example, if
+		you have a file <b>include/jazz/note.h</b>, then your source
+		files can include it simply with <b>#include "jazz/note.h"</b>.
+
+		<dt><b>tools</b>
+		<dd>
+		This subdirectory should contain all of your source
+		code for executables.  For each program that you build, you
+		will have one directory in <b>tools</b> that will contain that
+		program's source code.
+	</dl>
+
+	Typically, you will want to build your <b>lib</b> directory first
+	followed by your <b>tools</b> directory.
+
+	<!--===============================================================-->
+	<h2><a name="Makefile Variables">Makefile Variables</a><hr></h2>
+	<!--===============================================================-->
+	The LLVM build system provides several variables which you may
+	use.
+
+	<h3> Required Variables </h3>
+	<dl compact>
+		<dt>LEVEL
+		<dd>
+		This variable is the relative path from this Makefile to the
+		top directory of your project's source code.  For example, if
+		your source code is in /tmp/src, then the Makefile in
+		/tmp/src/jump/high would set LEVEL to "../..".
+	</dl>
+
+	<h3> Variables for Building Subdirectories</h3>
+	<dl compact>
+		<dt>DIRS
+		<dd>
+		This is a space separated list of subdirectories that should be
+		built.  They will be built, one at a time, in the order
+		specified.
+		<p>
+
+		<dt>PARALLEL_DIRS
+		<dd>
+		This is a list of directories that can be built in parallel.
+		These will be built after the directories in DIRS have been
+		built.
+		<p>
+
+		<dt>OPTIONAL_DIRS
+		<dd>
+		This is a list of directories that can be built if they exist,
+		but will not cause an error if they do not exist.  They are
+		built serially in the order in which they are listed.
+	</dl>
+
+	<h3> Variables for Building Libraries</h3>
+	<dl compact>
+		<dt>LIBRARYNAME
+		<dd>
+		This variable contains the base name of the library that will
+		be built.  For example, to build a library named
+		<tt>libsample.a</tt>, LIBRARYNAME should be set to
+		<tt>sample</tt>.
+		<p>
+
+		<dt>BUILD_ARCHIVE
+		<dd>
+		By default, a library is a <tt>.o</tt> file that is linked
+		directly into a program.  However, if you set the BUILD_ARCHIVE
+		variable, an archive library (sometimes known as a static
+		library) will be built instead.
+		<p>
+
+		<dt>SHARED_LIBRARY
+		<dd>
+		If SHARED_LIBRARY is defined in your Makefile, then the
+		Makefiles will generate a shared (or dynamic) library.
+	</dl>
+
+	<h3> Variables for Building Programs</h3>
+	<dl compact>
+		<dt>TOOLNAME
+		<dd>
+		This variable contains the name of the program that will
+		be built.  For example, to build an executable named
+		<tt>sample</tt>, TOOLNAME should be set to <tt>sample</tt>.
+		<p>
+
+		<dt>USEDLIBS
+		<dd>
+		This variable holds a space separated list of libraries that
+		should be linked into the program.  These libraries must either
+		be LLVM libraries or libraries that come from your <b>lib</b>
+		directory.  The libraries must be specified by their base name.
+		For example, to link libsample.a, you would set USEDLIBS to
+		<tt>sample</tt>.
+		<p>
+	</dl>
+
+	<h3> Miscellaneous Variables</h3>
+	<dl compact>
+		<dt>ExtraSource
+		<dd>
+		This variable contains a space separated list of extra source
+		files that needs to be built.  It is useful for including the
+		output of Lex and Yacc programs.
+		<p>
+
+		<dt>CFLAGS
+		<dt>CPPFLAGS
+		<dd>
+		This variable can be used to add options to the C and C++
+		compiler, respectively.  It is typically used to add options
+		that tell the compiler the location of additional directories
+		to search for header files.
+		<p>
+		It is highly suggested that you append to these variable as
+		opposed to overwriting them.  The master Makefiles may already
+		have useful options in them that you may not want to overwrite.
+		<p>
+	</dl>
+
+	<!--===============================================================-->
+	<h2><a name="Caveats">Caveats</a><hr></h2>
+	<!--===============================================================-->
+
+	Some caveats and known issues:
+	<ol>
+		<li>
+		The projects system currently uses the $HOME environment
+		variable in determining where object files should go.  If $HOME
+		is not set, then your path relative to the root directory may
+		be used to determine where your object files go.  It is
+		therefore advised that your source directory reside underneath
+		your home directory.
+	</ol>
+</body>
+</html>
author	John Criswell <criswell@uiuc.edu>	2003-07-03 15:37:52 +0000
committer	John Criswell <criswell@uiuc.edu>	2003-07-03 15:37:52 +0000
commit	f2413aedb6aca58dc690d81095193307a8df46ff (patch)
tree	36ddcd3300ea18504a9267f7c76ec8d918c7fd7e /docs/Projects.html
parent	5bfccb9defee2026e113c1fd694eb29b99d4f8a6 (diff)
download	llvm-f2413aedb6aca58dc690d81095193307a8df46ff.tar.gz llvm-f2413aedb6aca58dc690d81095193307a8df46ff.tar.bz2 llvm-f2413aedb6aca58dc690d81095193307a8df46ff.tar.xz