Merge pull request #182 from Wodann/feature/book

feat(book): add book to main repository

.github/workflows/ci.yml

@@ -59,7 +59,25 @@ jobs:
       - name: Install LLVM
         uses: ./.github/actions/install-llvm
 
-      - name: Cargo check
+      - name: Cargo build
+        uses: actions-rs/cargo@v1
+        continue-on-error: ${{ matrix.config.toolchain == 'nightly' }}
+        with:
+          command: build
+
+      - name: Install mdbook
+        if: ${{ matrix.config.os == 'ubuntu-latest' && matrix.config.toolchain == 'stable' }}
+        uses: actions-rs/[email protected]
+        with:
+          crate: mdbook
+          version: latest
+          use-tool-cache: true
+
+      - name: mdbook test
+        if: ${{ matrix.config.os == 'ubuntu-latest' && matrix.config.toolchain == 'stable' }}
+        run: mdbook test book -L target/debug/deps
+
+      - name: Cargo test
         uses: actions-rs/cargo@v1
         continue-on-error: ${{ matrix.config.toolchain == 'nightly' }}
         with:

.gitignore

@@ -29,4 +29,4 @@ Cargo.lock
 
 # Build artifacts
 *.munlib
-**/target/*
+**/target/*

.gitmodules

@@ -1,6 +1,10 @@
 [submodule "crates/mun_abi/c"]
 	path = crates/mun_abi/c
-	url = ../../mun-lang/abi-c
+	url = https://github.com/mun-lang/abi-c.git
 [submodule "crates/mun_runtime_capi/ffi"]
 	path = crates/mun_runtime_capi/ffi
-	url = ../../mun-lang/runtime-ffi.git
+	url = https://github.com/mun-lang/runtime-ffi.git
+[submodule "book/vendor/highlight.js"]
+	path = book/vendor/highlight.js
+	url = https://github.com/mun-lang/highlight.js.git
+	branch = add-mun

README.md

@@ -2,7 +2,8 @@
 
 [![Build Status][build-badge]][build]
 [![Crates.io][crates-badge]][crates]
-[![docs page][dosc-badge]][docs] 
+[![docs master][docs-master-badge]][docs-master]
+[![docs v0.2][docs-v0.2-badge]][docs-v0.2]
 [![MIT/Apache][licence-badge]][license]
 [![Join us on Discord][discord-badge]][discord]
 [![codecov][coverage-badge]][coverage]
@@ -17,8 +18,11 @@
 [coverage-badge]: https://img.shields.io/codecov/c/github/mun-lang/mun.svg
 [coverage]: https://codecov.io/gh/mun-lang/mun
 
-[dosc-badge]: https://img.shields.io/badge/docs-website-blue.svg
-[docs]: https://docs.mun-lang.org/
+[docs-master-badge]: https://img.shields.io/badge/docs-master-blue.svg
+[docs-master]: https://docs.mun-lang.org/
+
+[docs-v0.2-badge]: https://img.shields.io/badge/docs-v0.2-blue.svg
+[docs-v0.2]: https://docs.mun-lang.org/v0.2/
 
 [licence-badge]: https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue
 [license]: COPYRIGHT
@@ -32,31 +36,35 @@
 
 ## Features
 
-- **Ahead of time compilation** - Mun is compiled ahead of time (AOT), as opposed to being
-  interpreted or compiled just in time (JIT). By detecting errors in the code during AOT
-  compilation, an entire class of runtime errors is eliminated. This allows developers to stay
-  within the comfort of their IDE instead of having to switch between the IDE and target application
-  to debug runtime errors.
-
-- **Statically typed** - Mun resolves types at compilation time instead of at runtime, resulting in
-  immediate feedback when writing code and opening the door for powerful refactoring tools.
-
-- **First class hot-reloading** - Every aspect of Mun is designed with hot reloading in mind. Hot
-  reloading is the process of changing code and resources of a live application, removing the need
-  to start, stop and recompile an application whenever a function or value is changed.
-
-- **Performance** - AOT compilation combined with static typing ensure that Mun is compiled to
-  machine code that can be natively executed on any target platform. LLVM is used for compilation
-  and optimization, guaranteeing the best possible performance. Hot reloading does introduce a
-  slight runtime overhead, but it can be disabled for production builds to ensure the best possible
+- **Ahead of time compilation** - Mun is compiled ahead of time (AOT), as
+  opposed to being interpreted or compiled just in time (JIT). By detecting
+  errors in the code during AOT compilation, an entire class of runtime errors
+  is eliminated. This allows developers to stay within the comfort of their IDE
+  instead of having to switch between the IDE and target application to debug
+  runtime errors.
+
+- **Statically typed** - Mun resolves types at compilation time instead of at
+  runtime, resulting in immediate feedback when writing code and opening the
+  door for powerful refactoring tools.
+
+- **First class hot-reloading** - Every aspect of Mun is designed with hot
+  reloading in mind. Hot reloading is the process of changing code and resources
+  of a live application, removing the need to start, stop and recompile an
+  application whenever a function or value is changed.
+
+- **Performance** - AOT compilation combined with static typing ensure that Mun
+  is compiled to machine code that can be natively executed on any target
+  platform. LLVM is used for compilation and optimization, guaranteeing the best
+  possible performance. Hot reloading does introduce a slight runtime overhead,
+  but it can be disabled for production builds to ensure the best possible
   runtime performance.
 
-- **Cross compilation** - The Mun compiler is able to compile to all supported target platforms from
-  any supported compiler platform.
+- **Cross compilation** - The Mun compiler is able to compile to all supported
+  target platforms from any supported compiler platform.
 
-- **Powerful IDE integration** *not implemented yet* - The Mun language and compiler framework are
-  designed to support source code queries, allowing for powerful IDE integrations such as code
-  completion and refactoring tools.
+- **Powerful IDE integration** *not implemented yet* - The Mun language and
+  compiler framework are designed to support source code queries, allowing for
+  powerful IDE integrations such as code completion and refactoring tools.
 
 ## Example
 
@@ -119,14 +127,16 @@ fn on_heap() -> GC {
 
 ## Documentation
 
-[The Mun Programming Language Book](https://docs.mun-lang.org/)
+[The Mun Programming Language Book](https://docs.mun-lang.org/) is hosted on
+[netlify](https://www.netlify.com/).
 
 ## Pre-Built Binaries
 
 **[NOTE] We do not provide support for milestone releases**
 
-Download pre-built binaries of [milestone releases](https://github.com/mun-lang/mun/releases) for
-macOS, Linux, and Windows (64-bit only).
+Download pre-built binaries of [milestone
+releases](https://github.com/mun-lang/mun/releases) for macOS, Linux, and
+Windows (64-bit only).
 
 ## Building from Source
 
@@ -141,16 +151,18 @@ rustup](https://www.rust-lang.org/tools/install).
 
 #### LLVM
 
-Mun targets LLVM 7.1.0. Installing LLVM is platform dependant and as such can be a pain. The
-following steps are how we install LLVM on [our CI
+Mun targets LLVM 7.1.0. Installing LLVM is platform dependant and as such can be
+a pain. The following steps are how we install LLVM on [our CI
 runners](.github/actions/install-llvm/index.js):
 
-* ***nix**: Package managers of recent *nix distros can install binary versions of LLVM, e.g.:
+* ***nix**: Package managers of recent *nix distros can install binary versions
+  of LLVM, e.g.:
   ```bash
   # Ubuntu 18.04
   sudo apt install llvm-7 llvm-7-* liblld-7*
   ```
-* **Arch Linux** The binary version of LLVM can currently only be installed using an AUR helper, such as `yay`:
+* **Arch Linux** The binary version of LLVM can currently only be installed
+  using an AUR helper, such as `yay`:
   ```bash
   yay -Syu lld7-headers lld7-libs-static
   ```
@@ -162,26 +174,29 @@ runners](.github/actions/install-llvm/index.js):
   cd lld7
   makepkg -si
   ```
-  When running `llvm-config`, an error can occur signalling that `/usr/lib/libtinfo.so.5` is
-  missing. If a newer version is present, create a symlink; e.g. `ln -s /usr/lib/libtinfo.so.6
-  /usr/lib/libtinfo.so.5`), otherwise download the library.
-* **macOS**: [Brew](https://brew.sh/) contains a binary distribution of LLVM 7.1.0. However, as it's
-  not the latest version, it won't be added to the path. We are using
-  [llvm-sys](https://crates.io/crates/llvm-sys) to manage version, but another option is to export 
-  the `LLVM_SYS_70_PREFIX` variable, which will not clutter your `PATH`. To install:
+  When running `llvm-config`, an error can occur signalling that
+  `/usr/lib/libtinfo.so.5` is missing. If a newer version is present, create a
+  symlink; e.g. `ln -s /usr/lib/libtinfo.so.6 /usr/lib/libtinfo.so.5`),
+  otherwise download the library.
+* **macOS**: [Brew](https://brew.sh/) contains a binary distribution of LLVM
+  7.1.0. However, as it's not the latest version, it won't be added to the path.
+  We are using [llvm-sys](https://crates.io/crates/llvm-sys) to manage version,
+  but another option is to export the `LLVM_SYS_70_PREFIX` variable, which will
+  not clutter your `PATH`. To install:
   ```bash
   brew install llvm@7
   # Export LLVM_SYS_PREFIX to not clubber PATH
   export LLVM_SYS_PREFIX=$(brew --prefix llvm@7)
   ```
-* **windows**: Binary distrubutions are available for Windows on the LLVM website, but they
-  do not contain a number of libraries that are required by Mun. To avoid having to go to the 
-  trouble of compiling LLVM yourself, we created a
-  [repository](https://github.com/mun-lang/llvm-package-windows) that automatically compiles the
- required binaries. It also contains a
+* **windows**: Binary distrubutions are available for Windows on the LLVM
+  website, but they do not contain a number of libraries that are required by
+  Mun. To avoid having to go to the trouble of compiling LLVM yourself, we
+  created a [repository](https://github.com/mun-lang/llvm-package-windows) that
+  automatically compiles the required binaries. It also contains a
   [release](https://github.com/mun-lang/llvm-package-windows/releases/download/v7.1.0/llvm-7.1.0-windows-x64-msvc15.7z)
-  that you can download and extract to your machine. Once downloaded and extracted, add the `<extract_dir>/bin`
-  folder to the `PATH` environment variable.
+  that you can download and extract to your machine. Once downloaded and
+  extracted, add the `<extract_dir>/bin` folder to the `PATH` environment
+  variable.
 
 ### Clone source
 
@@ -197,12 +212,66 @@ git submodule update --init --recursive
 cargo build --release
 ```
 
+## Building Documentation
+
+Building the book requires
+[mdBook](https://github.com/rust-lang-nursery/mdBook), ideally version 0.3.x. To
+install it, run:
+
+```
+$ cargo install mdbook --vers [version-num]
+```
+
+The Mun book uses a [custom version of
+Highlight.js](https://github.com/mun-lang/highlight.js) to enable highlighting
+of Mun code. The build version of Highlight.js is required by mdbook in the
+`theme/` folder but it is not distributed with the source. Instead, it can be
+build by invoking the build script:
+
+```bash
+cd book
+./ci/build-highlight-js
+```
+
+Every time you change something in the custom version of highlight.js you have
+to call the above script to ensure you locally use the latest version.
+
+After generating the custom minified Highlight.js, to build the book, type:
+
+```
+$ mdbook build 
+```
+
+The output will be in the book subdirectory. To view the book, open it in your
+web browser.
+
+For local development use `mdbook serve` instead of `mdbook build`. This will
+start a local webserver on port `3000` that serves the book and rebuilds the
+content when changes are detected.
+
+All of the above is also combined in a single shell script that can be invoked
+by simply running:
+
+```bash
+./ci/build
+```
+
+To test the `rust` source code in the book, run:
+
+```bash
+mdbook test -L path/to/target/debug/deps
+```
+
+For this to work, there can only be one `libmun_runtime-{HASH}.rlib` file in the
+provided library path.
+
 ## License
 
 The Mun Runtime is licensed under either of
 
- * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or 
+ * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
    http://www.apache.org/licenses/LICENSE-2.0)
- * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+ * MIT license ([LICENSE-MIT](LICENSE-MIT) or
+   http://opensource.org/licenses/MIT)
 
  at your option.

book/.gitignore

@@ -0,0 +1,2 @@
+/book
+/theme/highlight.js

book/book.toml

@@ -0,0 +1,9 @@
+[book]
+authors = ["The Mun Team <[email protected]>"]
+language = "en"
+multilingual = false
+src = "src"
+title = "The Mun Programming Language"
+
+[output.html]
+additional-css = ["theme/mun.css"]

book/ci/build

@@ -0,0 +1,22 @@
+#!/bin/bash
+
+set -euo pipefail
+
+pushd ./book
+
+    # First build our custom highlight.js
+    ./ci/build-highlight-js
+
+    # Check if mdbook is installed, otherwise download the binaries
+    mdbook="mdbook"
+    if ! [ -x "$(command -v $mdbook)" ]; then 
+        echo "Installing mdbook.."
+        curl -sL https://github.com/rust-lang-nursery/mdBook/releases/download/v0.3.1/mdbook-v0.3.1-x86_64-unknown-linux-gnu.tar.gz | tar zxv
+        mdbook="./mdbook"
+    fi
+
+    # Actually build the book
+    echo 'Building book..'
+    $mdbook build
+
+popd

book/ci/build-highlight-js

@@ -0,0 +1,19 @@
+#!/bin/bash
+set -euo pipefail
+
+main() {
+    # prepare the git submodule, if it hasn't been already
+    git submodule init
+
+    # build the minified highlight.js source
+    pushd vendor/highlight.js
+        npm install
+        node tools/build.js rust bash mun cpp c typescript
+    popd
+
+    # copy the minified sources to the theme directory
+    mkdir -p theme
+    cp vendor/highlight.js/build/highlight.pack.js theme/highlight.js
+}
+
+main

book/listings/ch01-getting-started/listing01.mun

@@ -0,0 +1,16 @@
+pub fn fibonacci_n() -> i64 {
+    let n = arg();
+    fibonacci(n);
+}
+
+fn arg() -> i64 {
+    5
+}
+
+fn fibonacci(n: i64) -> i64 {
+    if n <= 1 {
+        n
+    } else {
+        fibonacci(n - 1) + fibonacci(n - 2)
+    }
+}

book/listings/ch01-getting-started/listing02.mun

@@ -0,0 +1,11 @@
+pub fn arg() -> i64 {
+    5
+}
+
+pub fn fibonacci(n: i64) -> i64 {
+    if n <= 1 {
+        n
+    } else {
+        fibonacci(n - 1) + fibonacci(n - 2)
+    }
+}

book/listings/ch01-getting-started/listing03.cpp

@@ -0,0 +1,24 @@
+#include <iostream>
+
+#include "mun/runtime.h"
+
+int main() {
+    if (argc < 2) {
+        return 1;
+    }
+
+    auto lib_path = argv[1];
+    if (auto runtime = mun::make_runtime(lib_path)) {
+        while (true) {
+            auto arg = mun::invoke_fn<int64_t>(*runtime, "arg").wait();
+            auto result =
+                mun::invoke_fn<int64_t>(*runtime, "fibonacci", arg).wait();
+            std::cout << "fibonacci(" << std::to_string(arg) << ") = " << result
+                      << std::endl;
+
+            runtime->update();
+        }
+    }
+
+    return 2;
+}