Port gitbook document to main

SUMMARY.md

@@ -0,0 +1,90 @@
+# Summary: structure of chapters and subchapters of the book
+
+* [WAMR Document Home Page](gitbook/home_page.md)
+
+## Basics
+
+* [Introduction](gitbook/basics/introduction/README.md)
+  * [WebAssembly](gitbook/basics/introduction/webassembly.md)
+  * [WAMR Project](gitbook/basics/introduction/wamr_project.md)
+  * [Security Feature](gitbook/basics/introduction/security_feature.md)
+
+* [Getting Started](gitbook/basics/getting-started/README.md)
+  * [Host Environment Preparation](gitbook/basics/getting-started/host_prerequsites.md)
+  * [Hello-world Program On Host](gitbook/basics/getting-started/on_host.md)
+  * [Docker Environment Preparation](doc/devcontainer.md)
+  * [Hello-world Program On Docker](gitbook/basics/getting-started/on_docker.md)
+  * [Build And Run WASM Application](doc/build_wasm_app.md)
+    * [More Tools To Create WASM Application](doc/other_wasm_compilers.md)
+
+## WAMR In Practice
+
+* [Tutorial](gitbook/tutorial/README.md)
+  * [WAMR Running Modes](gitbook/tutorial/running-modes/README.md)
+  * [Build Tutorial](gitbook/tutorial/build-tutorial/README.md)
+    * [Build iwasm](doc/build_wamr.md)
+    * [Build wamrc](gitbook/tutorial/build-tutorial/build_wamrc.md)
+  * [Language Embedding](gitbook/tutorial/language-embedding/README.md)
+    * [C/C++](doc/embed_wamr.md)
+    * [Python](language-bindings/python/README.md)
+    * [Go](language-bindings/go/README.md)
+  * [Debugging & IDE Support](gitbook/tutorial/debugging%26IDE-support/README.md)
+    * [WAMR Source Debugging With LLDB](doc/source_debugging.md)
+    * [VS Code Support](test-tools/wamr-ide/README.md)
+      * [Enable Debugging In VS Code](test-tools/wamr-ide/VSCode-Extension/README.md)
+      * [Move LLDB Binaries](test-tools/wamr-ide/VSCode-Extension/resource/debug/README.md)
+
+* [Advance Tutorial](gitbook/advance-tutorial/README.md)
+  * [Performance Test](gitbook/advance-tutorial/performance-benchmark/README.md)
+    * [PolyBench](tests/benchmarks/polybench/README.md)
+    * [CoreMark](tests/benchmarks/coremark/README.md)
+    * [Sightglass](tests/benchmarks/sightglass/README.md)
+    * [JetStream2](tests/benchmarks/jetstream/README.md)
+  * [Memory Usage Tunning](doc/memory_tune.md)
+  * [WAMR Porting Guide](doc/port_wamr.md)
+
+* [Features](gitbook/features/README.md)
+  * [Export Native APIs To WASM Applications](doc/export_native_api.md)
+    * [Example 1: Export C Functions to WASM](samples/basic/README.md)
+    * [Example 2: Using "native-lib"](samples/native-lib/README.md)
+  * [Multiple Modules As Dependencies](doc/multi_module.md)
+    * [Multi-modules Example](samples/multi-module/README.md)
+  * [Multi-thread, Pthread APIs And Thread Management](doc/pthread_library.md)
+    * [Multi-thread Example](samples/multi-thread/README.md)
+  * [Linux SGX(Intel Software Guard Extension) Support](doc/linux_sgx.md)
+  * [Linux SGX Remote Attestation](samples/sgx-ra/README.md)
+  * [XIP(Execution In Place) Support](doc/xip.md)
+  * [Socket Support](doc/socket_api.md)
+    * [Example: Use Socket Api in WAMR](samples/socket-api/README.md)
+  * [Post-MVP Features](gitbook/features/demo-examples/README.md)
+    * [WASM C API](samples/wasm-c-api/README.md)
+    * [128-bit SIMD](samples/workload/README.md)
+    * [Reference Types](samples/ref-types/README.md)
+
+* [More Examples](gitbook/examples/README.md)
+  * [File Interaction Of WASI](samples/file/README.md)
+  * [Same WASM Program Executing Concurrently](samples/spawn-thread/README.md)
+  * [Build And Run Workload](samples/workload/README.md)
+
+* [User Case](gitbook/features/user-case/README.md)
+
+## Programmer's Manual
+
+* [Programmer's Manual](gitbook/programmer's-manual/README.md)
+  * [C API Lists](gitbook/programmer's-manual/C_API_Lists.md)
+
+## Community
+
+* [How To Contribute](CONTRIBUTING.md)
+
+* [WAMR On Github](https://github.com/bytecodealliance/wasm-micro-runtime)
+
+* [WAMR Blogs](https://bytecodealliance.github.io/wamr.dev/)
+
+## Appendix
+
+* [Appendix A. Background Knowledge And Glossary Of Terms](gitbook/appendix/background_knowledge.md)
+
+* [Appendix B. WebAssembly Details](gitbook/appendix/webassembly_details.md)
+
+* [Appendix C. Complete WAMR Guide](README.md)

gitbook/advance-tutorial/README.md

@@ -0,0 +1,7 @@
+# Advance tutorial
+
+Welcome to the chapter of the advanced tutorial.
+
+If you care about performance(don't we all?), want to know whether WAMR stands out among other wasm runtimes with respect to your demands, or wish to fine-tune your wasm application's memory footprint. You could refer to [this section](performance-benchmark/README.md)
+
+In later sections, you can find the tutorial on how to use [application framework](../../doc/wamr_api.md) and [dynamic management](remote-applicatoin-management/README.md). Also, there is a tutorial on [how to port WAMR to the platform](../../doc/port_wamr.md)

gitbook/advance-tutorial/performance-benchmark/README.md

@@ -0,0 +1,18 @@
+# Performance Test
+
+Like word on the street said(no way it's just us saying!) or you may saw in previous chapters(maybe multiple times), WAMR is a **lightweight** standalone WebAssembly (WASM) runtime with **small footprint**, **high performance** and highly configurable features.
+
+Well, you don't have to take our word for it. You could run the [Benchmarks in our repo](https://github.com/bytecodealliance/wasm-micro-runtime/tree/main/tests/benchmarks) and decide whether the performance is good enough.
+
+We provide multiple benchmarks that you could try:
+
+- [PolyBench](../../../tests/benchmarks/polybench/README.md)
+- [CoreMark](../../../tests/benchmarks/coremark/README.md)
+- [Sightglass](../../../tests/benchmarks/sightglass/README.md)
+- [JetStream2](../../../tests/benchmarks/jetstream/README.md)
+
+For the memory footprint, you can refer to the links below.
+
+- [Performance and footprint data](https://github.com/bytecodealliance/wasm-micro-runtime/wiki/Performance): checkout [here](https://github.com/bytecodealliance/wasm-micro-runtime/wiki/Performance) for the performance and footprint data
+
+And in the next section, we provide tutorials on memory usage tuning. You can [profile memory usage](../../../doc/build_wamr.md#enable-memory-profiling-experiment) and [tunning memory usage](../../../doc/memory_tune.md)

gitbook/advance-tutorial/remote-applicatoin-management/README.md

@@ -0,0 +1,7 @@
+# Remote application management
+
+The WAMR application manager supports **remote application management**(check out local directory {WAMR-DIR}/core/app-mgr or [same directory on GitHub](https://github.com/bytecodealliance/wasm-micro-runtime/tree/main/core/app-mgr) for more) from the host environment or the cloud through any physical communications such as TCP, UPD, UART, BLE, etc. Its modular design makes it able to support application management for different managed runtimes.
+
+The tool **host_tool** (check out local directory {WAMR-DIR}/test-tools/host-tool or [same directory on GitHub](https://github.com/bytecodealliance/wasm-micro-runtime/tree/main/test-tools/host-tool) for more) communicates to the WAMR app manager for installing/uninstalling the wasm applications on the companion chip from the host system.
+
+We have two example demos of the use of **host_tool**. One is the [simple example](../../../samples/simple/README.md) using the tool "host_tool" to remotely install/uninstall wasm applications from the WAMR runtime over either TCP socket or UART cable; the other is the [IoT App Store Demo](../../../test-tools/IoT-APP-Store-Demo/README.md) showing the concept of remotely managing the device applications from the cloud.

gitbook/appendix/background_knowledge.md

@@ -0,0 +1,61 @@
+# Some background knowledge
+
+In this section, we aggregate some basic background knowledge and jargon in our project field. This section could be served as a refresher for those who have left academia for a while and cannot fully recall all the weary details and exact meaning of jargon in the Compiler course. Also, it would be a great primer for those who did not take such a course and are interested in such a field(and, of course, our fantastic WAMR project).
+
+We think providing such a section would be nice so that you do not have to Google around. If there is anything you find inaccurate, you think should be included, or even better, you have something for us that would perfect this section, do feel free to reach out to us on [GitHub](https://github.com/bytecodealliance/wasm-micro-runtime)!
+
+Let's dive right into our exciting recitation/learning journey without further ado!
+
+## 1. Compiler
+
+### 1.1 What is a Compiler?
+
+Strictly speaking(formal definition you usually find in textbooks), the compiler is a special computer program, a system program(serves as a platform for other software), to be more precise. It takes a source program as input and outputs a target program. The source program is written in the source programming language, and usually, it is a high-level programming language such as C/C++, Java, Rust, and so on. The target program is written in a target programming language would be a low-level programming language like assembly. Take C/C++ as an example, the input for the GCC compiler(component) is a C/C++ translation unit(a source file along with any header it used), and the output is platform-dependent assembly code.
+
+However, in our daily life, what we usually mean when we refer to the word compiler is the compiler toolchain, which comprises a compiler, assembler, and linker. The assembler is in charge of translating the compiled translation unit(object file) from assembly to truly machine-readable machine code. The linker is used to link all the parts of the program(object files) into one executable file. Together, they can translate our human-readable source code(potentially many files) into a program that can run on the machine.
+
+For now, we will mainly focus on the more strict definition because I think the concept and algorithm compiler use more closely pertain to our WAMR project.
+
+<!-- TODO: graph -->
+
+### 1.2 Structure and algorithm involved
+
+<!-- TODO: graph -->
+
+Since we alright know what a compiler is, now let's learn more details about compilers. First, let's talk about the structure of the compiler and the algorithm related to each part. Typically, the compiler consists of three parts, Front End, Optimizer and Back End:
+
+- Front End: in some sense, this part is more "mature." The theory involved and actual implementation is more or less stable nowadays. Its primary purpose is to gather textual information from source-language programs and understand it syntactically and semantically. After that, it encodes the knowledge it has into Intermediate Representation. The theory behind Front End is formal language theory(Scanners & Parsers) and lattice theory(Elaboration for type checking).
+
+- Optimizer: as the name suggests, the Optimizer's goal is to optimize our program's performance. Clever readers may be conscious of the difficulty when they hear the word "optimize." Indeed, the Optimizer is very challenging to design and implement since it's a vital part of compiler infrastructure and imposes a heavy performance impact. It analyses the input IR and transforms it into definitive IR, usually through multiple passes, gradually accumulating knowledge of the program and applying a better(hopefully) transformation to it. The output(definitive IR) is semantically equivalent to the input IR to preserve the original meaning of the program we are compiling. The theories and algorithms that could be used for Optimizer are too many to list here. Here are examples: Number theory, some graph algorithms for static analysis, and fixed-point algorithms for data-flow analysis. It's still an active field that attracts many people to research.
+
+- Back End: the Back End is in charge of mapping programs (in IR form) to low-level code forms that can run on the target machine. Usually, there is more than one Back End, so the compiler is portable for different platforms (ISA). Its main functionality includes instruction selection, register allocation, and instruction scheduling, in which many algorithms are applied, like heuristic search, graph coloring, and some dynamic programming. Like Optimizer, the Back End has many open problems to tackle and also is a field many people hold great interest in.
+
+## 2. Interpreter
+
+### 2.1 What is an Interpreter?
+
+The Interpreter is also a system computer program. Like the compiler, it takes a source program as input; but instead of outputting a target program, it directly executes the program line by line and returns the corresponding results. One thing worth noting is that it's not uncommon for an interpreter to adapt widely used techniques in the compilers to improve its performance. Sometimes they are even used together.
+
+Based on the levels of the source language(high or low) and compilation strategies, the interpreters can be divided into several different categories. Let's look at them in more detail in the following section.
+
+### 2.2  Technique and jargon in Interpreter
+
+- Bytecode:
+
+  The bytecode is a kind of low-level programming language in a very highly optimized and compact format. It could be the target language for the compiler. Because the instruction-like bytecode can be executed line by line in an interpreter on any platform, regardless of what hardware-related ISA it uses, it is also called p-code(portable). One example of bytecode you may be familiar with is Java bytecode.
+
+- Ahead-of-time(AOT) and Just-in-time(JIT) compilation:
+
+  - AOT: as the name suggests, the AOT compilation means that the compilation happens before the program run time. Normally the target language after  AOT compilation is some low-level machine code or bytecode. Then the compiled code can be executed by either a process VM or a normal computer.
+
+  - JIT: just in time compilation is a technique widely adopted by the Interpreter to improve its performance. It detects the heavily used code section when interpreting the program and compiles them into more efficient machine code. When that code section is called again, the machine code is executed rather than having the bytecode interpreted.
+
+## 3. Virtual machines
+
+When it comes to the word "Virtual Machines," we usually would remember or refer to that System virtual machines managed by hypervisors such as KVM, VirtualBox, or VMware. We often use them as a substitute for real computers to resolve dependency or compatibility issues for courses or daily work.
+
+But there is also another type of virtual machine you may have heard of(even you may get really confused at first) and related more closely to the field where our project is. Process (application) virtual machines provide an environment independent of hardware, aiming to run computer programs written in a certain language. Take JVM as an example. It provides an environment for Java bytecode to execute across many platforms.
+
+## 4. Runtime system
+
+It's a rather vague term that is really difficult to explain or understand. To make things worse, when people sometimes refer to it as runtime, it's easily confused with compilation runtime, runtime library. The runtime system is an infrastructure that participates in the creation and running of our program. Typically, the components are the execution environment(Application VM maybe) to provide a place for the program to run, and the compiler front end or/and compiler back end to do the necessary analysis, transformation(from source code to bytecode), and optimization.

gitbook/appendix/webassembly_details.md

@@ -0,0 +1,6 @@
+---
+description: "This page is under construction/refinement. p.s. wanna hear a construction joke? we are still working on it"
+---
+# WebAssembly details
+
+Meanwhile, if you can't wait to learn more about Wasm, check out this book: _WebAssembly in Action_. It's a great book showcasing wasm basics and how to use wasm with JavaScript inside a browser.

gitbook/basics/getting-started/README.md

@@ -0,0 +1,13 @@
+# Getting started: a hello world program
+
+In this chapter, you'll learn how to run a simple hello world wasm program on your host or the Docker environment using WAMR. The docker tutorial is recommended so you don't have to worry about all the platform-related dependencies and compatibility problems. The hello world program will give you a taste of what our WAMR could do as server-side runtime and ready you for a more detailed guide at the end of this chapter. The [latter guide](../../../doc/build_wasm_app.md) covers the meaning of the compile and build option in detail and gives suggestions on fine-tuning your wasm module. More example programs can be found in [chapter 4. features](../../features/README.md)
+
+Now, here is the last piece of gibberish before you get your hand dirty:
+
+Clone our source code repo and use
+
+```sh
+git clone https://github.com/bytecodealliance/wasm-micro-runtime.git
+```
+
+Or download from <https://github.com/bytecodealliance/wasm-micro-runtime> use any way you like

gitbook/basics/getting-started/host_prerequsites.md

@@ -0,0 +1,40 @@
+# Prerequisites for your host environment
+
+## Ubuntu
+
+First, install the needed packages and libraries.
+
+```sh
+apt-get update \
+  && apt-get install -y apt-transport-https apt-utils build-essential \
+  ca-certificates curl g++-multilib git gnupg \
+  libgcc-9-dev lib32gcc-9-dev lsb-release \
+  ninja-build ocaml ocamlbuild python2.7 \
+  software-properties-common tree tzdata \
+  unzip valgrind vim wget zip --no-install-recommends
+```
+
+Then install CMake and wasi-sdk-16.0
+
+```sh
+wget --progress=dot:giga -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | gpg --dearmor - | tee /usr/share/keyrings/kitware-archive-keyring.gpg > /dev/null \
+  && echo 'deb [signed-by=/usr/share/keyrings/kitware-archive-keyring.gpg] https://apt.kitware.com/ubuntu/ bionic main' | tee /etc/apt/sources.list.d/kitware.list >/dev/null \
+  && apt-get update \
+  && rm /usr/share/keyrings/kitware-archive-keyring.gpg \
+  && apt-get install -y kitware-archive-keyring --no-install-recommends \
+  && apt-get install -y cmake --no-install-recommends 
+
+wget -c --progress=dot:giga https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-16/wasi-sdk-16.0-linux.tar.gz -P /opt \
+  && tar xf /opt/wasi-sdk-16.0-linux.tar.gz -C /opt \
+  && ln -fs /opt/wasi-sdk-16.0 /opt/wasi-sdk \
+  && rm /opt/wasi-sdk-16.0-linux.tar.gz
+```
+
+This should be sufficient to build WAMR and run our hello world program.
+<!-- 
+TODO:
+
+## MacOS
+
+## Windows
+ -->

gitbook/basics/getting-started/on_docker.md

@@ -0,0 +1,26 @@
+# Using docker
+
+Now that we have set up docker, we could run the following command directly in VS Code terminal(or the bash of your if you prefer ssh docker container directly).
+
+Similarly, build iwasm vmcore.
+
+```sh
+cd product-mini/platforms/linux
+mkdir build && cd build
+cmake ..
+make 
+```
+
+Then you are ready to go to the directory that contains the hello world program and copy our iwasm vmcore
+
+```sh
+cp iwasm ../../../app-samples/hello-world
+cd ../../../app-samples/hello-world
+./build.sh
+```
+
+Now you can execute your first wasm program!
+
+```sh
+./iwasm test.wasm
+```

gitbook/basics/getting-started/on_host.md

@@ -0,0 +1,26 @@
+# Compile, build and test hello world on the host
+
+Now we have our host set up, we can build our hello world program and run it using WAMR.
+
+First, build iwasm vmcore on your platform.
+
+```sh
+cd ${WAMR-dir}/product-mini/platforms/${your platform}
+mkdir build && cd build
+cmake ..
+make 
+```
+
+Then you are ready to go to the directory that contains the hello world program and copy our iwasm vmcore
+
+```sh
+cp iwasm ../../../app-samples/hello-world
+cd ${WAMR-dir}/product-mini/app-samples/hello-world
+./build.sh
+```
+
+Now you could execute your first wasm program!
+
+```sh
+./iwasm test.wasm
+```

gitbook/basics/introduction/README.md

@@ -0,0 +1,5 @@
+# Introduction
+
+In this chapter, we will introduce you to some basic knowledge about [WebAssembly](./webassembly.md) and our project [WAMR](./wamr_project.md). And discuss the security feature that Webassembly language itself and WAMR's enhancement can bring in [this section](./security_feature.md)
+
+We understand because our backgrounds vary, some terms in the following section may sound familiar but vague. We have a primer in [Appendix A](../../appendix/background_knowledge.md) gathering some details about background knowledge(compiler, interpreter, runtime system, all other jargon) that may be helpful and free you from googling around. You are more than welcome to check it out.