diff options
| -rw-r--r-- | docs/GettingStartedVS.html | 254 |
1 files changed, 91 insertions, 163 deletions
diff --git a/docs/GettingStartedVS.html b/docs/GettingStartedVS.html index 5a86199..40b1877 100644 --- a/docs/GettingStartedVS.html +++ b/docs/GettingStartedVS.html @@ -14,19 +14,12 @@ <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="#quickstart">Getting Started</a> <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> @@ -47,26 +40,23 @@ <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 + <p>The Visual Studio port has some limitations. It is suitable for + use 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> + is then assembled into an executable. You can output object files + in COFF format, though. You can also indirectly create executables + by using the C backend.</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><tt>llvm-gcc</tt> is based on GCC, which cannot be bootstrapped + using VC++. There are <tt>llvm-gcc</tt> binaries based on MinGW + available on the + LLVM <a href="http://www.llvm.org/releases/download.html"> download + page</a>. Eventually, <a href="http://clang.llvm.org">Clang</a> + will be able to produce executables on Windows.</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><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> @@ -76,89 +66,6 @@ <!-- *********************************************************************** --> <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> <!-- *********************************************************************** --> @@ -206,59 +113,82 @@ changes are continually making the VS support better.</p> <!-- *********************************************************************** --> <div class="doc_section"> - <a name="starting"><b>Getting Started with LLVM</b></a> + <a name="quickstart"><b>Getting Started</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> +<p>Here's the short story for getting up and running quickly with LLVM:</p> - <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> +<ol> + <li>Read the documentation.</li> + <li>Seriously, read the documentation.</li> + <li>Remember that you were warned twice about reading the documentation.</li> -</div> + <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> -<!-- ======================================================================= --> -<div class="doc_subsection"> - <a name="objfiles">The Location of LLVM Object Files</a> -</div> + <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>Once 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. 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, although + installation is not mandatory for using LLVM. Another + important option is LLVM_TARGETS_TO_BUILD, which controls the + LLVM target architectures that are included on the build. If + you want to run the <a href="#tutorial">example described + below</a> you must set that variable to "X86;CBackend".</li> + <li>See the <a href="CMake.html">LLVM CMake guide</a> for + detailed information about how to configure the LLVM + build.</li> + </ul> + </li> -<div class="doc_text"> + <li>Start Visual Studio + <ul> + <li>In the directory you created the project files will have + an <tt>llvm.sln</tt> file, just double-click on that to open + Visual Studio.</li> + </ul></li> - <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> + <li>Build the LLVM Suite: + <ul> + <li>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> + <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 or run it from the command line. The + program will print the corresponding fibonacci value.</li> + </ul></li> - <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> +</ol> </div> @@ -296,9 +226,9 @@ int main() { <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> + <p><b>Note: you will need the llvm-gcc binaries from the + LLVM <a href="http://www.llvm.org/releases/download.html"> + download page</a></b></p></li> <li><p>Run the program using the just-in-time compiler:</p> @@ -327,6 +257,15 @@ int main() { <pre> % llc -march=c hello.bc </pre> + + <p><b>Note: you need to add the C backend to the LLVM build, + which amounts to setting the CMake + variable <i>LLVM_TARGETS_TO_BUILD</i> to "X86;CBackend" when + you generate the VS solution files. See + the <a href="CMake.html">LLVM CMake guide</a> for more + information about how to configure the LLVM + build.</b></p></li> + </div></li> <li><p>Compile to binary using Microsoft C:</p> @@ -360,17 +299,6 @@ int main() { <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> |