Documentation and examples improvements

llvm-svn: 51739

tools/llvmc2/doc/LLVMC-Reference.rst

@@ -125,15 +125,31 @@ debugging), run ``llvmc2 --view-graph``. You will need ``dot`` and
 ``gsview`` installed for this to work properly.
 
 
-The 'case' construct
---------------------
+The 'case' expression
+---------------------
 
-The 'case' construct can be used to calculate weights for optional
+The 'case' construct can be used to calculate weights of the optional
 edges and to choose between several alternative command line strings
 in the ``cmd_line`` tool property. It is designed after the
-similarly-named construct in functional languages and takes the
-form ``(case (test_1), statement_1, (test_2), statement_2,
-... (test_N), statement_N)``.
+similarly-named construct in functional languages and takes the form
+``(case (test_1), statement_1, (test_2), statement_2, ... (test_N),
+statement_N)``. The statements are evaluated only if the corresponding
+tests evaluate to true.
+
+Examples::
+
+    // Increases edge weight by 5 if "-A" is provided on the
+    // command-line, and by 5 more if "-B" is also provided.
+    (case
+        (switch_on "A"), (inc_weight 5),
+        (switch_on "B"), (inc_weight 5))
+
+    // Evaluates to "cmdline1" if option "-A" is provided on the
+    // command line, otherwise to "cmdline2"
+    (case
+        (switch_on "A"), ("cmdline1"),
+        (default), ("cmdline2"))
+
 
 * Possible tests are:
 
@@ -153,7 +169,8 @@ form ``(case (test_1), statement_1, (test_2), statement_2,
     belongs to the current input language set. Example:
     ```(input_languages_contain "c++")``.
 
-  - ``default`` - Always evaluates to true. Should be used
+  - ``default`` - Always evaluates to true. Should always be the last
+    test in the ``case`` expression.
 
   - ``and`` - A standard logical combinator that returns true iff all
     of its arguments return true. Used like this: ``(and (test1),

tools/llvmc2/doc/LLVMC-Tutorial.rst

@@ -64,8 +64,8 @@ At the heart of LLVMC is the idea of a transformation graph: vertices
 in this graph are tools, and edges signify that there is a
 transformation path between two tools (for example, assembly source
 produced by the compiler can be transformed into executable code by an
-assembler). A special node named ``root`` is used to mark graph entry
-points.
+assembler). A special node named ``root`` is used to mark the graph
+entry points.
 
 Tool descriptions are basically lists of properties: most properties
 in the example above should be self-explanatory; the ``sink`` property

tools/llvmc2/doc/Makefile

@@ -0,0 +1,13 @@
+
+RST2HTML=rst2html
+
+all : LLVMC-Reference.html LLVMC-Tutorial.html
+
+LLVMC-Tutorial.html : LLVMC-Tutorial.rst
+	$(RST2HTML) $< $@
+
+LLVMC-Reference.html : LLVMC-Reference.rst
+	$(RST2HTML) $< $@
+
+clean :
+	rm *.html

tools/llvmc2/examples/Clang.td

@@ -0,0 +1,48 @@
+// A (first stab at a) replacement for the Clang's ccc script.
+// To compile, use this command:
+//    make TOOLNAME=ccc GRAPH=examples/Clang.td
+
+include "Common.td"
+
+// TOFIX: It should be possible to use a string list in the 'in_language'
+// tool property. There should be also an 'in_language' test in the
+// 'case' construct.
+
+def clang : Tool<
+[(in_language "c"),
+ (out_language "llvm-bitcode"),
+ (output_suffix "bc"),
+ (cmd_line (case (switch_on "E"), "clang -E $INFILE -o $OUTFILE",
+                 (default), "clang -emit-llvm-bc $INFILE -o $OUTFILE")),
+ (switch_option "E", (stop_compilation), (output_suffix "i"),
+   (help "Stop after the preprocessing stage, do not run the compiler")),
+ (sink)
+]>;
+
+// Default linker
+def llvm_ld : Tool<
+[(in_language "llvm-bitcode"),
+ (out_language "executable"),
+ (output_suffix "out"),
+ (cmd_line "llvm-ld -native -disable-internalize $INFILE -o $OUTFILE"),
+ (prefix_list_option "L", (forward), (help "Specify a library search path")),
+ (join)
+]>;
+
+// Language map
+
+def LanguageMap : LanguageMap<
+    [LangToSuffixes<"c++", ["cc", "cp", "cxx", "cpp", "CPP", "c++", "C"]>,
+     LangToSuffixes<"c", ["c"]>,
+     LangToSuffixes<"objective-c", ["m"]>,
+     LangToSuffixes<"c-cpp-output", ["i"]>,
+     LangToSuffixes<"objective-c-cpp-output", ["mi"]>
+     ]>;
+
+// Compilation graph
+
+def CompilationGraph : CompilationGraph<[
+    Edge<root, clang>,
+    Edge<clang, llvm_ld>
+    ]>;
+

tools/llvmc2/examples/Simple.td

@@ -1,4 +1,6 @@
 // A simple wrapper for gcc.
+// To compile, use this command:
+//    make TOOLNAME=llvmc_simple GRAPH=examples/Simple.td
 
 include "Common.td"