[llvm-commits] [llvm] r158947 - in /llvm/trunk/docs: GettingStartedVS.html GettingStartedVS.rst userguides.rst

Michael J. Spencer bigcheesegs at gmail.com
Thu Jun 21 16:27:09 PDT 2012


Author: mspencer
Date: Thu Jun 21 18:27:09 2012
New Revision: 158947

URL: http://llvm.org/viewvc/llvm-project?rev=158947&view=rev
Log:
[docs] Sphinxify GettingStartedVS. Patch by Mikael Lyngvig!

Added:
    llvm/trunk/docs/GettingStartedVS.rst
Removed:
    llvm/trunk/docs/GettingStartedVS.html
Modified:
    llvm/trunk/docs/userguides.rst

Removed: llvm/trunk/docs/GettingStartedVS.html
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/GettingStartedVS.html?rev=158946&view=auto
==============================================================================
--- llvm/trunk/docs/GettingStartedVS.html (original)
+++ llvm/trunk/docs/GettingStartedVS.html (removed)
@@ -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>

Added: llvm/trunk/docs/GettingStartedVS.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/GettingStartedVS.rst?rev=158947&view=auto
==============================================================================
--- llvm/trunk/docs/GettingStartedVS.rst (added)
+++ llvm/trunk/docs/GettingStartedVS.rst Thu Jun 21 18:27:09 2012
@@ -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/>`_
+

Modified: llvm/trunk/docs/userguides.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/userguides.rst?rev=158947&r1=158946&r2=158947&view=diff
==============================================================================
--- llvm/trunk/docs/userguides.rst (original)
+++ llvm/trunk/docs/userguides.rst Thu Jun 21 18:27:09 2012
@@ -8,6 +8,7 @@
 
    CommandGuide/index
    DeveloperPolicy
+   GettingStartedVS
    FAQ
    Lexicon
    Packaging





More information about the llvm-commits mailing list