llvm.org GIT mirror llvm / 7a9fd01 docs / Projects.html
7a9fd01

Tree @7a9fd01 (Download .tar.gz)

Projects.html @7a9fd01raw · history · blame

<!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>