Converted to sphinx/rst and improved some things along the way

Author: f0rki

Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    = 
+SPHINXBUILD   = sphinx-build-3
+SPHINXPROJ    = MappingHighLevelConstructstoLLVMIR
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

README.md

@@ -0,0 +1,72 @@
+Mapping High Level Constructs to LLVM IR
+========================================
+
+`Click here to read the book on
+gitbooks.io <https://f0rki.gitbooks.io/mapping-high-level-constructs-to-llvm-ir/content/>`__
+
+About
+-----
+
+This is a gitbook dedicated to providing a description on how LLVM based
+compilers map high-level language constructs into the LLVM intermediate
+representation (IR).
+
+This document targets people interested in how modern compilers work and
+want to learn how high-level language constructs can be implemented.
+Currently the books focuses on C and C++, but contributions about other
+languages targeting LLVM are highly welcome. This document should help
+to make the learning curve less steep for aspiring LLVM users.
+
+For the sake of simplicity, we'll be working with a 32-bit target
+machine so that pointers and word-sized operands are 32-bits. Also, for
+the sake of readability we do not mangle (encode) names. Rather, they
+are given simple, easy-to-read names that reflect their purpose. A
+production compiler for any language that supports overloading would
+generally need to mangle the names so as to avoid conflicts between
+symbols.
+
+Contributing
+------------
+
+The repository for this gitbook is hosted on
+`github <https://github.com/f0rki/mapping-high-level-constructs-to-llvm-ir>`__.
+All contributions are welcome. If you find an error file an
+`Issue <https://github.com/f0rki/mapping-high-level-constructs-to-llvm-ir/issues>`__
+or fork the repository `and create a
+pull-request <https://github.com/f0rki/mapping-high-level-constructs-to-llvm-ir/pulls>`__.
+
+License
+-------
+
+UNLESS OTHERWISE NOTED, THE CONTENTS OF THIS REPOSITORY ARE LICENSED
+UNDER THE CREATIVE COMMONS ATTRIBUTION - SHARE ALIKE 4.0 INTERNATIONAL
+LICENSE
+
+.. figure:: https://i.creativecommons.org/l/by-sa/4.0/88x31.png
+   :alt: https://creativecommons.org/licenses/by-sa/4.0/
+
+   https://creativecommons.org/licenses/by-sa/4.0/
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   a-quick-primer/index
+   basic-constructs/index
+   control-structures/index
+   object-oriented-constructs/index
+   exception-handling/index
+   advanced-constructs/index
+   interoperating-with-a-runtime-library/index
+   interfacing-to-the-operating-system/index
+   epilogue/index
+   appendix-a-how-to-implement-a-string-type-in-llvm/index
+
+
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

README.rst

@@ -0,0 +1 @@
+*

SUMMARY.md

@@ -0,0 +1,59 @@
+**************
+A Quick Primer
+**************
+
+Here are a few things that you should know before reading this document:
+
+-  LLVM IR is not machine code, but sort of the step just above
+   assembly. So some things look more like a high-level language (like
+   functions and the strong typing). Other looks more like low-level
+   assembly (e.g. branching, basic-blocks).
+-  LLVM IR is strongly typed so expect to be told when you do something
+   wrong.
+-  LLVM IR does not differentiate between signed and unsigned integers.
+-  LLVM IR assumes two's complement signed integers so that say
+   ``trunc`` works equally well on signed and unsigned integers.
+-  Global symbols begin with an at sign (``@``).
+-  Local symbols begin with a percent symbol (``%``).
+-  All symbols must be declared or defined.
+-  Don't worry that the LLVM IR at times can seem somewhat lengthy when
+   it comes to expressing something; the optimizer will ensure the
+   output is well optimized and you'll often see two or three LLVM IR
+   instructions be coalesced into a single machine code instruction.
+-  If in doubt, consult the Language Reference. If there is a conflict
+   between the Language Reference and this document, this document is
+   wrong!
+-  All LLVM IR examples are presented without a data layout and without
+   a target triple. You need to add those yourself, if you want to
+   actually build and run the samples. Get them from ``clang`` for your
+   platform.
+
+Some Useful LLVM Tools
+----------------------
+
+The most important LLVM tools for use with this article are as follows:
+
++----------------+----------------+---------------+-----------+---------------------+
+| Name           | Function       | Reads         | Writes    | Arguments           |
++================+================+===============+===========+=====================+
+| ``clang``      | C Compiler     | ``.c``        | ``.ll``   | ``-emit-llvm -S``   |
++----------------+----------------+---------------+-----------+---------------------+
+| ``clang++``    | C++ Compiler   | ``.cpp``      | ``.ll``   | ``-emit-llvm -S``   |
++----------------+----------------+---------------+-----------+---------------------+
+| ``llvm-dis``   | Disassembler   | ``.bc``       | ``.ll``   |                     |
++----------------+----------------+---------------+-----------+---------------------+
+| ``opt``        | Optimizer      | ``.bc/.ll``   | same      |                     |
++----------------+----------------+---------------+-----------+---------------------+
+| ``llc``        | IR Compiler    | ``.ll``       | ``.s``    |                     |
++----------------+----------------+---------------+-----------+---------------------+
+
+While you are playing around with generating or writing LLVM IR, you may
+want to add the option ``-fsanitize=undefined`` to Clang/Clang++ insofar
+you use either of those. This option makes Clang/Clang++ insert run-time
+checks in places where it would normally output an ``ud2`` instruction.
+This will likely save you some trouble if you happen to generate
+undefined LLVM IR. Please notice that this option only works for C and
+C++ compiles.
+
+Note that you can use ``.ll`` or ``.bc`` files as input files for
+``clang(++)`` and compile full executables from bitcode files.

_build/.gitignore

@@ -0,0 +1,2 @@
+Closures
+--------