diff options
| author | Michael J. Spencer <bigcheesegs@gmail.com> | 2012-06-21 23:27:09 +0000 |
|---|---|---|
| committer | Michael J. Spencer <bigcheesegs@gmail.com> | 2012-06-21 23:27:09 +0000 |
| commit | 55eda324c4c5591e00306bfaa701b049a74e569e (patch) | |
| tree | fd97e217501e517b1db729290bfdc3bf8b4885da | |
| parent | 2a5422b1a6955977d05af48222c86c77c7549484 (diff) | |
| download | external_llvm-55eda324c4c5591e00306bfaa701b049a74e569e.zip external_llvm-55eda324c4c5591e00306bfaa701b049a74e569e.tar.gz external_llvm-55eda324c4c5591e00306bfaa701b049a74e569e.tar.bz2 | |
[docs] Sphinxify GettingStartedVS. Patch by Mikael Lyngvig!
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@158947 91177308-0d34-0410-b5e6-96231b3b80d8
| -rw-r--r-- | docs/GettingStartedVS.html | 368 | ||||
| -rw-r--r-- | docs/GettingStartedVS.rst | 234 | ||||
| -rw-r--r-- | docs/userguides.rst | 1 |
3 files changed, 235 insertions, 368 deletions
diff --git a/docs/GettingStartedVS.html b/docs/GettingStartedVS.html deleted file mode 100644 index b0ed824..0000000 --- a/docs/GettingStartedVS.html +++ /dev/null @@ -1,368 +0,0 @@ -<!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="_static/llvm.css" type="text/css"> -</head> -<body> - -<h1> - Getting Started with the LLVM System using Microsoft Visual Studio -</h1> - -<ul> - <li><a href="#overview">Overview</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="#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> -</ul> - -<div class="doc_author"> - <p>Written by: <a href="http://llvm.org/">The LLVM Team</a></p> -</div> - - -<!-- *********************************************************************** --> -<h2> - <a name="overview"><b>Overview</b></a> -</h2> -<!-- *********************************************************************** --> - -<div> - - <p>Welcome to LLVM on Windows! This document only covers LLVM on Windows using - Visual Studio, not mingw or cygwin. In order to get started, you first need to - know some basic information.</p> - - <p>There are many different projects that compose LLVM. The first is the LLVM - suite. This contains all of the tools, libraries, and header files needed to - use LLVM. It contains an assembler, disassembler, - bitcode analyzer and bitcode optimizer. It also contains a test suite that can - be used to test the LLVM tools.</p> - - <p>Another useful project on Windows is - <a href="http://clang.llvm.org/">clang</a>. Clang is a C family - ([Objective]C/C++) compiler. Clang mostly works on Windows, but does not - currently understand all of the Microsoft extensions to C and C++. Because of - this, clang cannot parse the C++ standard library included with Visual Studio, - nor parts of the Windows Platform SDK. However, most standard C programs do - compile. Clang can be used to emit bitcode, directly emit object files or - even linked executables using Visual Studio's <tt>link.exe</tt></p> - - <p>The large 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.</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> - -<!-- *********************************************************************** --> -<h2> - <a name="requirements"><b>Requirements</b></a> -</h2> -<!-- *********************************************************************** --> - -<div> - - <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> - -<!-- ======================================================================= --> -<h3> - <a name="hardware"><b>Hardware</b></a> -</h3> - -<div> - - <p>Any system that can adequately run Visual Studio 2008 is fine. The LLVM - source tree and object files, libraries and executables will consume - approximately 3GB.</p> - -</div> - -<!-- ======================================================================= --> -<h3><a name="software"><b>Software</b></a></h3> -<div> - - <p>You will need Visual Studio 2008 or higher. Earlier versions of Visual - Studio have bugs, are not completely compatible, or do not support the C++ - standard well enough.</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>If you would like to run the LLVM tests you will need - <a href="http://www.python.org/">Python</a>. Versions 2.4-2.7 are known to - work. You will need <a href="http://gnuwin32.sourceforge.net/">"GnuWin32"</a> - tools, too.</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> - -<!-- *********************************************************************** --> -<h2> - <a name="quickstart"><b>Getting Started</b></a> -</h2> -<!-- *********************************************************************** --> - -<div> - -<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/trunk llvm</tt></li> - <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 simplest 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. - <li>See the <a href="CMake.html">LLVM CMake guide</a> for - detailed information about how to configure the LLVM - build.</li> - </ul> - </li> - - <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> - - <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> - - <li>Test LLVM on Visual Studio: - <ul> - <li>If %PATH% does not contain GnuWin32, you may specify LLVM_LIT_TOOLS_DIR - on CMake for the path to GnuWin32.</li> - <li>You can run LLVM tests by merely building the project - "check". The test results will be shown in the VS output - window.</li> - </ul> - </li> - - <!-- FIXME: Is it up-to-date? --> - <li>Test LLVM: - <ul> - <li>The LLVM tests can be run by <tt>cd</tt>ing to the llvm source directory - and running: - -<div class="doc_code"> -<pre> -% llvm-lit test -</pre> -</div> - - <p>Note that quite a few of these test will fail.</p> - </li> - - <li>A specific test or test directory can be run with: - -<div class="doc_code"> -<pre> -% llvm-lit test/path/to/test -</pre> -</div> - </li> - </ul> -</ol> - -</div> - -<!-- *********************************************************************** --> -<h2> - <a name="tutorial">An Example Using the LLVM Tool Chain</a> -</h2> -<!-- *********************************************************************** --> - -<div> - -<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> -% clang -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>Alternatively you can directly output an executable with clang with: - </p> - -<div class="doc_code"> -<pre> -% clang hello.c -o hello.exe -</pre> -</div> - - <p>The <tt>-o hello.exe</tt> is required because clang currently outputs - <tt>a.out</tt> when neither <tt>-o</tt> nor <tt>-c</tt> are given.</p> - - <li><p>Run the program using the just-in-time compiler:</p> - -<div class="doc_code"> -<pre> -% lli hello.bc -</pre> -</div> - - <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 object code using the LLC code generator:</p> - -<div class="doc_code"> -<pre> -% llc -filetype=obj hello.bc -</pre> -</div></li> - - <li><p>Link to binary using Microsoft link:</p> - -<div class="doc_code"> -<pre> -% link hello.obj -defaultlib:libcmt -</pre> -</div> - - <li><p>Execute the native code program:</p> - -<div class="doc_code"> -<pre> -% hello.exe -</pre> -</div></li> -</ol> - -</div> - -<!-- *********************************************************************** --> -<h2> - <a name="problems">Common Problems</a> -</h2> -<!-- *********************************************************************** --> - -<div> - -<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> - -<!-- *********************************************************************** --> -<h2> - <a name="links">Links</a> -</h2> -<!-- *********************************************************************** --> - -<div> - -<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> -</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="http://llvm.org/">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date$ -</address> -</body> -</html> diff --git a/docs/GettingStartedVS.rst b/docs/GettingStartedVS.rst new file mode 100644 index 0000000..7d773b7 --- /dev/null +++ b/docs/GettingStartedVS.rst @@ -0,0 +1,234 @@ +.. _winvs: + +================================================================== +Getting Started with the LLVM System using Microsoft Visual Studio +================================================================== + +.. contents:: + :local: + + +Overview +======== +Welcome to LLVM on Windows! This document only covers LLVM on Windows using +Visual Studio, not mingw or cygwin. In order to get started, you first need to +know some basic information. + +There are many different projects that compose LLVM. The first is the LLVM +suite. This contains all of the tools, libraries, and header files needed to +use LLVM. It contains an assembler, disassembler, +bitcode analyzer and bitcode optimizer. It also contains a test suite that can +be used to test the LLVM tools. + +Another useful project on Windows is `Clang <http://clang.llvm.org/>`_. +Clang is a C family ([Objective]C/C++) compiler. Clang mostly works on +Windows, but does not currently understand all of the Microsoft extensions +to C and C++. Because of this, clang cannot parse the C++ standard library +included with Visual Studio, nor parts of the Windows Platform SDK. However, +most standard C programs do compile. Clang can be used to emit bitcode, +directly emit object files or even linked executables using Visual Studio's +``link.exe``. + +The large LLVM test suite cannot be run on the Visual Studio port at this +time. + +Most of the tools build and work. ``bugpoint`` does build, but does +not work. + +Additional information about the LLVM directory structure and tool chain +can be found on the main `Getting Started <GettingStarted.html>`_ page. + + +Requirements +============ +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. + +Hardware +-------- +Any system that can adequately run Visual Studio 2008 is fine. The LLVM +source tree and object files, libraries and executables will consume +approximately 3GB. + +Software +-------- +You will need Visual Studio 2008 or higher. Earlier versions of Visual +Studio have bugs, are not completely compatible, or do not support the C++ +standard well enough. + +You will also need the `CMake <http://www.cmake.org/>`_ build system since it +generates the project files you will use to build with. + +If you would like to run the LLVM tests you will need `Python +<http://www.python.org/>`_. Versions 2.4-2.7 are known to work. You will need +`GnuWin32 <http://gnuwin32.sourceforge.net/>`_ tools, too. + +Do not install the LLVM directory tree into a path containing spaces (e.g. +``C:\Documents and Settings\...``) as the configure step will fail. + + +Getting Started +=============== +Here's the short story for getting up and running quickly with LLVM: + +1. Read the documentation. +2. Seriously, read the documentation. +3. Remember that you were warned twice about reading the documentation. +4. Get the Source Code + + * With the distributed files: + + 1. ``cd <where-you-want-llvm-to-live>`` + 2. ``gunzip --stdout llvm-VERSION.tar.gz | tar -xvf -`` + (*or use WinZip*) + 3. ``cd llvm`` + + * With anonymous Subversion access: + + 1. ``cd <where-you-want-llvm-to-live>`` + 2. ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm`` + 3. ``cd llvm`` + +5. Use `CMake <http://www.cmake.org/>`_ to generate up-to-date project files: + + * Once CMake is installed then the simplest 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. + * See the `LLVM CMake guide <CMake.html>`_ for detailed information about + how to configure the LLVM build. + +6. Start Visual Studio + + * In the directory you created the project files will have an ``llvm.sln`` + file, just double-click on that to open Visual Studio. + +7. Build the LLVM Suite: + + * 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. + * 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. + +8. Test LLVM on Visual Studio: + + * If ``%PATH%`` does not contain GnuWin32, you may specify + ``LLVM_LIT_TOOLS_DIR`` on CMake for the path to GnuWin32. + * You can run LLVM tests by merely building the project "check". The test + results will be shown in the VS output window. + +.. FIXME: Is it up-to-date? + +9. Test LLVM: + + * The LLVM tests can be run by changing directory to the llvm source + directory and running: + + .. code-block:: bat + + C:\..\llvm> llvm-lit test + + Note that quite a few of these test will fail. + + A specific test or test directory can be run with: + + .. code-block:: bat + + C:\..\llvm> llvm-lit test/path/to/test + + +An Example Using the LLVM Tool Chain +==================================== + +1. First, create a simple C file, name it '``hello.c``': + + .. code-block:: c + + #include <stdio.h> + int main() { + printf("hello world\n"); + return 0; + } + +2. Next, compile the C file into a LLVM bitcode file: + + .. code-block:: bat + + C:\..> clang -c hello.c -emit-llvm -o hello.bc + + This will create the result file ``hello.bc`` 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 ``lli`` tool, + compile it to native assembly with the ``llc``, optimize or analyze it + further with the ``opt`` tool, etc. + + Alternatively you can directly output an executable with clang with: + + .. code-block:: bat + + C:\..> clang hello.c -o hello.exe + + The ``-o hello.exe`` is required because clang currently outputs ``a.out`` + when neither ``-o`` nor ``-c`` are given. + +3. Run the program using the just-in-time compiler: + + .. code-block:: bat + + C:\..> lli hello.bc + +4. Use the ``llvm-dis`` utility to take a look at the LLVM assembly code: + + .. code-block:: bat + + C:\..> llvm-dis < hello.bc | more + +5. Compile the program to object code using the LLC code generator: + + .. code-block:: bat + + C:\..> llc -filetype=obj hello.bc + +6. Link to binary using Microsoft link: + + .. code-block:: bat + + C:\..> link hello.obj -defaultlib:libcmt + +7. Execute the native code program: + + .. code-block:: bat + + C:\..> hello.exe + + +Common Problems +=============== +If you are having problems building or using LLVM, or if you have any other +general questions about LLVM, please consult the `Frequently Asked Questions +<FAQ.html>`_ page. + + +Links +===== +This document is just an **introduction** 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: + +* `LLVM homepage <http://llvm.org/>`_ +* `LLVM doxygen tree <http://llvm.org/doxygen/>`_ + diff --git a/docs/userguides.rst b/docs/userguides.rst index f1267dc..1b44c48 100644 --- a/docs/userguides.rst +++ b/docs/userguides.rst @@ -8,6 +8,7 @@ User Guides CommandGuide/index DeveloperPolicy + GettingStartedVS FAQ Lexicon Packaging |