diff options
Diffstat (limited to 'docs/GettingStartedVS.html')
| -rw-r--r-- | docs/GettingStartedVS.html | 417 |
1 files changed, 417 insertions, 0 deletions
diff --git a/docs/GettingStartedVS.html b/docs/GettingStartedVS.html new file mode 100644 index 0000000000..5a86199f7e --- /dev/null +++ b/docs/GettingStartedVS.html @@ -0,0 +1,417 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> + <title>Getting Started with LLVM System for Microsoft Visual Studio</title> + <link rel="stylesheet" href="llvm.css" type="text/css"> +</head> +<body> + +<div class="doc_title"> + Getting Started with the LLVM System using Microsoft Visual Studio +</div> + +<ul> + <li><a href="#overview">Overview</a> + <li><a href="#quickstart">Getting Started Quickly (A Summary)</a> + <li><a href="#requirements">Requirements</a> + <ol> + <li><a href="#hardware">Hardware</a> + <li><a href="#software">Software</a> + </ol></li> + + <li><a href="#starting">Getting Started with LLVM</a> + <ol> + <li><a href="#terminology">Terminology and Notation</a> + <li><a href="#objfiles">The Location of LLVM Object Files</a> + </ol></li> + + <li><a href="#tutorial">An Example Using the LLVM Tool Chain</a> + <li><a href="#problems">Common Problems</a> + <li><a href="#links">Links</a> +</ul> + +<div class="doc_author"> + <p>Written by: + <a href="mailto:jeffc@jolt-lang.org">Jeff Cohen</a> + </p> +</div> + + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="overview"><b>Overview</b></a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + + <p>The Visual Studio port at this time is experimental. It is suitable for + use only if you are writing your own compiler front end or otherwise have a + need to dynamically generate machine code. The JIT and interpreter are + functional, but it is currently not possible to generate assembly code which + is then assembled into an executable. You can indirectly create executables + by using the C back end.</p> + + <p>To emphasize, there is no C/C++ front end currently available. + <tt>llvm-gcc</tt> is based on GCC, which cannot be bootstrapped using VC++. + Eventually there should be a <tt>llvm-gcc</tt> based on Cygwin or MinGW that + is usable. There is also the option of generating bitcode files on Unix and + copying them over to Windows. But be aware the odds of linking C++ code + compiled with <tt>llvm-gcc</tt> with code compiled with VC++ is essentially + zero.</p> + + <p>The LLVM test suite cannot be run on the Visual Studio port at this + time.</p> + + <p>Most of the tools build and work. <tt>bugpoint</tt> does build, but does + not work. The other tools 'should' work, but have not been fully tested.</p> + + <p>Additional information about the LLVM directory structure and tool chain + can be found on the main <a href="GettingStarted.html">Getting Started</a> + page.</p> + +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="quickstart"><b>Getting Started Quickly (A Summary)</b></a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + +<p>Here's the short story for getting up and running quickly with LLVM:</p> + +<ol> + <li>Read the documentation.</li> + <li>Seriously, read the documentation.</li> + <li>Remember that you were warned twice about reading the documentation.</li> + + <li>Get the Source Code + <ul> + <li>With the distributed files: + <ol> + <li><tt>cd <i>where-you-want-llvm-to-live</i></tt> + <li><tt>gunzip --stdout llvm-<i>version</i>.tar.gz | tar -xvf -</tt> + <i> or use WinZip</i> + <li><tt>cd llvm</tt></li> + </ol></li> + + <li>With anonymous Subversion access: + <ol> + <li><tt>cd <i>where-you-want-llvm-to-live</i></tt></li> + <li><tt>svn co http://llvm.org/svn/llvm-project/llvm-top/trunk llvm-top + </tt></li> + <li><tt>make checkout MODULE=llvm</tt> + <li><tt>cd llvm</tt></li> + </ol></li> + </ul></li> + + <li> Use <a href="http://www.cmake.org/">CMake</a> to generate up-to-date + project files: + <ul><li>This step is currently optional as LLVM does still come with a + normal Visual Studio solution file, but it is not always kept up-to-date + and will soon be deprecated in favor of the multi-platform generator + CMake.</li> + <li>If CMake is installed then the most simple way is to just start the + CMake GUI, select the directory where you have LLVM extracted to, and + the default options should all be fine. The one option you may really + want to change, regardless of anything else, might be the + CMAKE_INSTALL_PREFIX setting to select a directory to INSTALL to once + compiling is complete.</li> + <li>If you use CMake to generate the Visual Studio solution and project + files, then the Solution will have a few extra options compared to the + current included one. The projects may still be built individually, but + to build them all do not just select all of them in batch build (as some + are meant as configuration projects), but rather select and build just + the ALL_BUILD project to build everything, or the INSTALL project, which + first builds the ALL_BUILD project, then installs the LLVM headers, libs, + and other useful things to the directory set by the CMAKE_INSTALL_PREFIX + setting when you first configured CMake.</li> + </ul> + </li> + + <li>Start Visual Studio + <ul> + <li>If you did not use CMake, then simply double click on the solution + file <tt>llvm/win32/llvm.sln</tt>.</li> + <li>If you used CMake, then the directory you created the project files, + the root directory will have an <tt>llvm.sln</tt> file, just + double-click on that to open Visual Studio.</li> + </ul></li> + + <li>Build the LLVM Suite: + <ul> + <li>Simply build the solution.</li> + <li>The Fibonacci project is a sample program that uses the JIT. Modify + the project's debugging properties to provide a numeric command line + argument. The program will print the corresponding fibonacci value.</li> + </ul></li> + +</ol> + +<p>It is strongly encouraged that you get the latest version from Subversion as +changes are continually making the VS support better.</p> + +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="requirements"><b>Requirements</b></a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + + <p>Before you begin to use the LLVM system, review the requirements given + below. This may save you some trouble by knowing ahead of time what hardware + and software you will need.</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="hardware"><b>Hardware</b></a> +</div> + +<div class="doc_text"> + + <p>Any system that can adequately run Visual Studio .NET 2005 SP1 is fine. + The LLVM source tree and object files, libraries and executables will consume + approximately 3GB.</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"><a name="software"><b>Software</b></a></div> +<div class="doc_text"> + + <p>You will need Visual Studio .NET 2005 SP1 or higher. The VS2005 SP1 + beta and the normal VS2005 still have bugs that are not completely + compatible. VS2003 would work except (at last check) it has a bug with + friend classes that you can work-around with some minor code rewriting + (and please submit a patch if you do). Earlier versions of Visual Studio + do not support the C++ standard well enough and will not work.</p> + + <p>You will also need the <a href="http://www.cmake.org/">CMake</a> build + system since it generates the project files you will use to build with.</p> + + <p> + Do not install the LLVM directory tree into a path containing spaces (e.g. + C:\Documents and Settings\...) as the configure step will fail.</p> + +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="starting"><b>Getting Started with LLVM</b></a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + +<p>The remainder of this guide is meant to get you up and running with +LLVM using Visual Studio and to give you some basic information about the LLVM +environment.</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="terminology">Terminology and Notation</a> +</div> + +<div class="doc_text"> + +<p>Throughout this manual, the following names are used to denote paths +specific to the local system and working environment. <i>These are not +environment variables you need to set but just strings used in the rest +of this document below</i>. In any of the examples below, simply replace +each of these names with the appropriate pathname on your local system. +All these paths are absolute:</p> + +<dl> + <dt>SRC_ROOT</dt> + <dd><p>This is the top level directory of the LLVM source tree.</p></dd> + + <dt>OBJ_ROOT</dt> + <dd><p>This is the top level directory of the LLVM object tree (i.e. the + tree where object files and compiled programs will be placed. It is + fixed at SRC_ROOT/win32).</p></dd> +</dl> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="objfiles">The Location of LLVM Object Files</a> +</div> + +<div class="doc_text"> + + <p>The object files are placed under <tt>OBJ_ROOT/Debug</tt> for debug builds + and <tt>OBJ_ROOT/Release</tt> for release (optimized) builds. These include + both executables and libararies that your application can link against.</p> + + <p>The files that <tt>configure</tt> would create when building on Unix are + created by the <tt>Configure</tt> project and placed in + <tt>OBJ_ROOT/llvm</tt>. You application must have OBJ_ROOT in its include + search path just before <tt>SRC_ROOT/include</tt>.</p> + +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="tutorial">An Example Using the LLVM Tool Chain</a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + +<ol> + <li><p>First, create a simple C file, name it 'hello.c':</p> + +<div class="doc_code"> +<pre> +#include <stdio.h> +int main() { + printf("hello world\n"); + return 0; +} +</pre></div></li> + + <li><p>Next, compile the C file into a LLVM bitcode file:</p> + +<div class="doc_code"> +<pre> +% llvm-gcc -c hello.c -emit-llvm -o hello.bc +</pre> +</div> + + <p>This will create the result file <tt>hello.bc</tt> which is the LLVM + bitcode that corresponds the the compiled program and the library + facilities that it required. You can execute this file directly using + <tt>lli</tt> tool, compile it to native assembly with the <tt>llc</tt>, + optimize or analyze it further with the <tt>opt</tt> tool, etc.</p> + + <p><b>Note: while you cannot do this step on Windows, you can do it on a + Unix system and transfer <tt>hello.bc</tt> to Windows. Important: + transfer as a binary file!</b></p></li> + + <li><p>Run the program using the just-in-time compiler:</p> + +<div class="doc_code"> +<pre> +% lli hello.bc +</pre> +</div> + + <p>Note: this will only work for trivial C programs. Non-trivial programs + (and any C++ program) will have dependencies on the GCC runtime that + won't be satisfied by the Microsoft runtime libraries.</p></li> + + <li><p>Use the <tt>llvm-dis</tt> utility to take a look at the LLVM assembly + code:</p> + +<div class="doc_code"> +<pre> +% llvm-dis < hello.bc | more +</pre> +</div></li> + + <li><p>Compile the program to C using the LLC code generator:</p> + +<div class="doc_code"> +<pre> +% llc -march=c hello.bc +</pre> +</div></li> + + <li><p>Compile to binary using Microsoft C:</p> + +<div class="doc_code"> +<pre> +% cl hello.cbe.c +</pre> +</div> + + <p>Note: this will only work for trivial C programs. Non-trivial programs + (and any C++ program) will have dependencies on the GCC runtime that won't + be satisfied by the Microsoft runtime libraries.</p></li> + + <li><p>Execute the native code program:</p> + +<div class="doc_code"> +<pre> +% hello.cbe.exe +</pre> +</div></li> +</ol> + +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="problems">Common Problems</a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + + <ul> + <li>In Visual C++, if you are linking with the x86 target statically, the + linker will remove the x86 target library from your generated executable or + shared library because there are no references to it. You can force the + linker to include these references by using + <tt>"/INCLUDE:_X86TargetMachineModule"</tt> when linking. In the Visual + Studio IDE, this can be added in +<tt>Project Properties->Linker->Input->Force Symbol References</tt>. + </li> + </ul> + +<p>If you are having problems building or using LLVM, or if you have any other +general questions about LLVM, please consult the <a href="FAQ.html">Frequently +Asked Questions</a> page.</p> + +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="links">Links</a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + +<p>This document is just an <b>introduction</b> to how to use LLVM to do +some simple things... there are many more interesting and complicated things +that you can do that aren't documented here (but we'll gladly accept a patch +if you want to write something up!). For more information about LLVM, check +out:</p> + +<ul> + <li><a href="http://llvm.org/">LLVM homepage</a></li> + <li><a href="http://llvm.org/doxygen/">LLVM doxygen tree</a></li> + <li><a href="http://llvm.org/docs/Projects.html">Starting a Project + that Uses LLVM</a></li> +</ul> + +</div> + +<!-- *********************************************************************** --> + +<hr> +<address> + <a href="http://jigsaw.w3.org/css-validator/check/referer"><img + src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a> + <a href="http://validator.w3.org/check/referer"><img + src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a> + + <a href="mailto:jeffc@jolt-lang.org">Jeff Cohen</a><br> + <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br> + Last modified: $Date$ +</address> +</body> +</html> |