Skip to content

Commit c554374

Browse files
3dgen3dgen
committed
zz
1 parent 622c794 commit c554374

File tree

391 files changed

+164538
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

391 files changed

+164538
-0
lines changed

‎.bookignore

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# only for gitbook
2+
3+
/docs
4+
/examples

‎.editorconfig

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# http://editorconfig.org/
2+
3+
root = true
4+
5+
# Unix-style newlines with a newline ending every file
6+
[*]
7+
charset = utf-8
8+
end_of_line = lf
9+
trim_trailing_whitespace = true
10+
insert_final_newline = true
11+
12+
[*]
13+
indent_style = tab
14+
indent_size = 4
15+
tab_width = 4
16+
17+
[*.{go,ts,js,c,cc,cpp,h,py,proto}]
18+
charset = utf-8
19+
indent_style = tab
20+
tab_width = 4
21+
22+
# Matches the exact files either package.json or .travis.yml
23+
[{package.json,.travis.yml}]
24+
indent_style = space
25+
indent_size = 2

‎.gitattributes

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
*.go linguist-language=WebAssembly

‎.gitignore

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Node rules:
2+
## Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
3+
.grunt
4+
5+
## Dependency directory
6+
## Commenting this out is preferred by some people, see
7+
## https://docs.npmjs.com/misc/faq#should-i-check-my-node_modules-folder-into-git
8+
node_modules
9+
10+
# Book build output
11+
_book
12+
13+
# eBook build output
14+
*.epub
15+
*.mobi
16+
#*.pdf
17+
18+
*.o
19+
*.obj
20+
*.exe
21+
22+
# macOS
23+
.DS_Store
24+
25+
*.a
26+
*.lib
27+
*.so
28+
*.dll
29+
*.obj
30+
*.o
31+
a.out
32+
33+
.oracle_jre_usage
34+
35+
# wasm
36+
*.wasm
37+
*.wasm2wat.txt
38+
39+
*.map
40+
41+
book.pdf
42+
book_*.pdf
43+
44+
# emcc
45+
*.out.js
46+
47+
# go
48+
go.mod
49+
go.sum

‎en/README.md

+101
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# WebAssembly friendly programming with C/C++
2+
3+
This book introduces the use of C/C++ for WebAssembly development. For the basics of WebAssembly, please refer to the "WebAssembly Primer"(Simplified Chinese), the sale address:
4+
5+
- EPUB：[https://www.epubit.com/book/detail/40619](https://www.epubit.com/book/detail/40619)
6+
- JD：[https://item.jd.com/12499372.html](https://item.jd.com/12499372.html)
7+
8+
----
9+
10+
![](cover.png)
11+
12+
- Author: Ending，Github [@3dgen](https://github.com/3dgen)
13+
- Author: ChaiShushan，Github [@chai2010](https://github.com/chai2010)，Twitter [@chaishushan](https://twitter.com/chaishushan)
14+
- Translator: Ending，Github [@3dgen](https://github.com/3dgen)
15+
- Translator: yushih, Github [@yushih](https://github.com/yushih)
16+
- Project: https://github.com/3dgen/cppwasm-book
17+
18+
## Preface
19+
20+
> *Ending's law: "Any application that can be compiled to WebAssembly, will be compiled to WebAssembly eventually."*
21+
22+
WebAssembly is the newest virtual machine standard for the web. C/C++ source code can be compiled into the WebAssembly binary format(.wasm) through the Emscripten toolchain, and then imported into web pages for JavaScript calls - this means that programs written in C/C++ can run in the web page.
23+
24+
This book introduces how to develope WebAssembly modules by C/C++ from the basic use of Emscripten; some general design principles and technical frameworks are proposed based on the first-hand experience gained by the author in the actual project.
25+
26+
We believe that an ideal Web-oriented C/C++ project should be insensitive to the compilation target - can be compiled to native code, or can be compiled to WebAssembly and run in the web page, the switch between each other only need to change the target configuration. So, we can make full use of the powerful development, debugging, analysis, testing and other functions of the existing IDE environment to improve project quality and reduce development costs.
27+
28+
However, the operating environment of WebAssembly is very different from the native code. Therefore, in order to achieve the above ideal goal, the characteristics (or limitations) of the Web environment must be fully considered, from the overall framework to the interface design and even to the data exchange between functions. This is the connotation of "WebAssembly friendly" implemented in this book.
29+
30+
## Read online
31+
32+
- [SUMMARY.md](SUMMARY.md)
33+
- https://3dgen.cn/cppwasm-book
34+
35+
## Reference
36+
37+
- ["WebAssembly Primer"](https://www.epubit.com/book/detail/40619)
38+
- [https://github.com/chai2010/awesome-wasm-zh](https://github.com/chai2010/awesome-wasm-zh)
39+
40+
----
41+
42+
## Progress
43+
44+
* [Chapter 1 Getting started with Emscripten](ch1-quick-guide/readme.md)
45+
* [x] [1.1 Installing Emscripten](ch1-quick-guide/ch1-01-install.md)
46+
* [x] [1.2 Hello, world!](ch1-quick-guide/ch1-02-helloworld.md)
47+
* [x] [1.3 Taking a look at the Emscripten glue code](ch1-quick-guide/ch1-03-glue-code.md)
48+
* [x] [1.4 Selecting compilation target](ch1-quick-guide/ch1-04-compile.md)
49+
50+
* [Chapter 2 Connecting C and JavaScript](ch2-c-js/readme.md)
51+
* [x] [2.1 Calling compiled C functions from JavaScript](ch2-c-js/ch2-01-js-call-c.md)
52+
* [x] [2.2 Implement C API in JavaScript](ch2-c-js/ch2-02-implement-c-api-in-js.md)
53+
* [x] [2.3 Memory model](ch2-c-js/ch2-03-mem-model.md)
54+
* [x] [2.4 Exchange data between C and JavaScript](ch2-c-js/ch2-04-data-exchange.md)
55+
* [x] [2.5 Using `EM_ASM`](ch2-c-js/ch2-05-em-asm.md)
56+
* [x] [2.6 Using `emscripten_run_script`](ch2-c-js/ch2-06-run-script.md)
57+
* [x] [2.7 Using `ccall`/`cwrap`](ch2-c-js/ch2-07-ccall-cwrap.md)
58+
* [x] [2.8 Supplement](ch2-c-js/ch2-08-ext.md)
59+
60+
* [Chapter 3 Emscripten runtime](ch3-runtime/readme.md)
61+
* [x] [3.1 Runtime lifecycle](ch3-runtime/ch3-01-main.md)
62+
* [x] [3.2 Message loop](ch3-runtime/ch3-02-message-loop.md)
63+
* [x] [3.3 File system](ch3-runtime/ch3-03-fs.md)
64+
* [x] [3.4 Memory management](ch3-runtime/ch3-04-mem.md)
65+
* [x] [3.5 Customize Module object](ch3-runtime/ch3-05-module.md)
66+
* [x] [3.6 Summary](ch3-runtime/ch3-06-summary.md)
67+
68+
* [Chapter 4 General techniques that WebAssembly friendly](ch4-techniques/readme.md)
69+
* [x] [4.1 Message loop detaching](ch4-techniques/ch4-01-msg-loop-detach.md)
70+
* [x] [4.2 Memory alignment](ch4-techniques/ch4-02-align.md)
71+
* [x] [4.3 Exporting C++ objects using the C interface](ch4-techniques/ch4-03-export-obj.md)
72+
* [x] [4.4 Lifecycle control for C++ object](ch4-techniques/ch4-04-obj-life-cycle.md)
73+
* [x] [4.5 Importing JavaScript object using C interface](ch4-techniques/ch4-05-import-js-obj.md)
74+
* [x] [4.6 Be careful with `int64`](ch4-techniques/ch4-06-int64-issue.md)
75+
* [x] [4.7 Forget about filesystem](ch4-techniques/ch4-07-forget-about-fs.md)
76+
77+
* [Chapter 5 Network IO](ch5-net/readme.md)
78+
* [x] [5.1 XMLHttpRequest](ch5-net/ch5-01-http.md)
79+
* [x] [5.2 WebSocket](ch5-net/ch5-02-websocket.md)
80+
<!--* [ ] 5.3 fetch-->
81+
82+
* [Chapter 6 Multithreading](ch6-threads/readme.md)
83+
* [x] [6.1 Multithreading in JavaScript](ch6-threads/ch6-01-worker.md)
84+
* [x] [6.2 Using Emscripten in Web Worker](ch6-threads/ch6-02-sample.md)
85+
<!--* [ ] 6.3 A simple framework for multithreading-->
86+
87+
* [Chapter 7 GUI](ch7-gui/readme.md)
88+
* [x] [7.1 Canvas](ch7-gui/ch7-01-canvas.md)
89+
* [x] [7.2 Mouse events](ch7-gui/ch7-02-mouse.md)
90+
* [x] [7.3 Keyboard events](ch7-gui/ch7-03-keyboard.md)
91+
* [x] [7.4 Conway's Game of Life](ch7-gui/ch7-04-life.md)
92+
93+
<!--* Chapter 8 Project management
94+
* [ ] 8.1 Using Makefile
95+
* [ ] 8.2 Using static library-->
96+
97+
----
98+
99+
## Copyright
100+
101+

‎en/SUMMARY.md

+48
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Summary
2+
3+
* [Chapter 1 Getting started with Emscripten](ch1-quick-guide/readme.md)
4+
* [1.1 Installing Emscripten](ch1-quick-guide/ch1-01-install.md)
5+
* [1.2 Hello, world!](ch1-quick-guide/ch1-02-helloworld.md)
6+
* [1.3 Taking a look at the Emscripten glue code](ch1-quick-guide/ch1-03-glue-code.md)
7+
* [1.4 Selecting compilation target](ch1-quick-guide/ch1-04-compile.md)
8+
9+
* [Chapter 2 Connecting C and JavaScript](ch2-c-js/readme.md)
10+
* [2.1 Calling compiled C functions from JavaScript](ch2-c-js/ch2-01-js-call-c.md)
11+
* [2.2 Implement C API in JavaScript](ch2-c-js/ch2-02-implement-c-api-in-js.md)
12+
* [2.3 Memory model](ch2-c-js/ch2-03-mem-model.md)
13+
* [2.4 Exchange data between C and JavaScript](ch2-c-js/ch2-04-data-exchange.md)
14+
* [2.5 Using `EM_ASM`](ch2-c-js/ch2-05-em-asm.md)
15+
* [2.6 Using `emscripten_run_script`](ch2-c-js/ch2-06-run-script.md)
16+
* [2.7 Using `ccall`/`cwrap`](ch2-c-js/ch2-07-ccall-cwrap.md)
17+
* [2.8 Supplement](ch2-c-js/ch2-08-ext.md)
18+
19+
* [Chapter 3 Emscripten runtime](ch3-runtime/readme.md)
20+
* [3.1 Runtime lifecycle](ch3-runtime/ch3-01-main.md)
21+
* [3.2 Message loop](ch3-runtime/ch3-02-message-loop.md)
22+
* [3.3 File system](ch3-runtime/ch3-03-fs.md)
23+
* [3.4 Memory management](ch3-runtime/ch3-04-mem.md)
24+
* [3.5 Customize Module object](ch3-runtime/ch3-05-module.md)
25+
* [3.6 Summary](ch3-runtime/ch3-06-summary.md)
26+
27+
* [Chapter 4 General techniques that WebAssembly friendly](ch4-techniques/readme.md)
28+
* [4.1 Message loop detaching](ch4-techniques/ch4-01-msg-loop-detach.md)
29+
* [4.2 Memory alignment](ch4-techniques/ch4-02-align.md)
30+
* [4.3 Exporting C++ objects using the C interface](ch4-techniques/ch4-03-export-obj.md)
31+
* [4.4 Lifecycle control for C++ object](ch4-techniques/ch4-04-obj-life-cycle.md)
32+
* [4.5 Importing JavaScript object using C interface](ch4-techniques/ch4-05-import-js-obj.md)
33+
* [4.6 Be careful with `int64`](ch4-techniques/ch4-06-int64-issue.md)
34+
* [4.7 Forget about filesystem](ch4-techniques/ch4-07-forget-about-fs.md)
35+
36+
* [Chapter 5 Network IO](ch5-net/readme.md)
37+
* [5.1 XMLHttpRequest](ch5-net/ch5-01-http.md)
38+
* [5.2 WebSocket](ch5-net/ch5-02-websocket.md)
39+
40+
* [Chapter 6 Multithreading](ch6-threads/readme.md)
41+
* [6.1 Multithreading in JavaScript](ch6-threads/ch6-01-worker.md)
42+
* [6.2 Using Emscripten in Web Worker](ch6-threads/ch6-02-sample.md)
43+
44+
* [Chapter 7 GUI](ch7-gui/readme.md)
45+
* [7.1 Canvas](ch7-gui/ch7-01-canvas.md)
46+
* [7.2 Mouse events](ch7-gui/ch7-02-mouse.md)
47+
* [7.3 Keyboard events](ch7-gui/ch7-03-keyboard.md)
48+
* [7.4 Conway's Game of Life](ch7-gui/ch7-04-life.md)

‎en/book.json

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
{
2+
"gitbook": "3.x",
3+
"title": "WebAssembly friendly programming with C/C++",
4+
"description": "WebAssembly friendly programming with C/C++ -- Emscripten practice",
5+
"language": "en",
6+
7+
"structure": {
8+
"readme": "preface.md"
9+
},
10+
11+
"pluginsConfig": {
12+
"theme-default": {
13+
"showLevel": false
14+
}
15+
},
16+
17+
"plugins": [
18+
"-search"
19+
]
20+
}

‎en/ch1-quick-guide/ch1-01-install.md

+86
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# 1.1 Installing Emscripten
2+
3+
Emscripten includes the complete set of tools include LLVM/Node.js/Python/Java/etc. that required to compile C/C++ code into WebAssembly, which does not depend on any other compiler environment.
4+
5+
## 1.1.1 Installing Emscripten using the `emsdk` command line
6+
7+
Emsdk is a set of Python 2 based scripts, so you need to install Python 2.7.12 or newer first . Python download address: [https://www.python.org/downloads/] (https://www.python.org/downloads/)
8+
9+
### `Downloading emsdk`
10+
11+
Once Python is ready, download the emsdk toolkit. If you're familiar with git, just use the following command to clone the emsdk library to local folder:
12+
13+
```
14+
git clone https://github.com/juj/emsdk.git
15+
```
16+
17+
If you are not familiar with git, you can visit [https://github.com/juj/emsdk](https://github.com/juj/emsdk) then download the emsdk library and extract it via "Clone or download" at the top right of the page. Figure:
18+
19+
![](images/download_emsdk.png)
20+
21+
### `Installing and activating Emscripten`
22+
23+
For MacOS or Linux users, `cd` into the folder where emsdk is located in a terminal and execute the following command:
24+
25+
```
26+
./emsdk update
27+
./emsdk install latest
28+
```
29+
30+
Emsdk will download and install the latest components of Emscripten from the Internet automatically. After the installation is complete, execute the following command to activate Emscripten:
31+
32+
```
33+
./emsdk activate latest
34+
```
35+
36+
Everytime a new terminal instance was created, you should `cd` into the folder where emsdk is located, and execute the following command to activate Emscripten environment variables for the current terminal:
37+
38+
```
39+
source ./emsdk_env.sh
40+
```
41+
42+
The installation on Windows is basically the same, the difference is to use `emsdk.bat` instead of `emsdk`, use `emsdk_env.bat` instead of `source./emsdk_env.sh`. The following commands are used to install and activate Emscripten:
43+
44+
```
45+
emsdk.bat update
46+
emsdk.bat install latest
47+
emsdk.bat activate latest
48+
```
49+
50+
The following commands are used to activate Emscripten environment variables:
51+
52+
```
53+
emsdk_env.bat
54+
```
55+
56+
> **tips** Installation and activation only need to be run once. On Windows, if you want to register Emscripten's environment variables as global variables, you can run `emsdk.bat activate latest --global` as an administrator. This will change the system environment variables so that you don't need to run `emsdk_env.bat` in every newly created terminal, this method has potential side effects: it changes environment variables to Emscripten's built-in Node.js/Python/Java, and if other versions of these components are installed on the system, conflicts may arise.
57+
58+
## 1.1.2 Installing Emscripten in a Docker environment
59+
60+
If you are familiar with Docker, you can also install Emscripten in a Docker environment. Emscripten in the Docker is completely isolated and does not have any impact on the host environment. The `apiaryio/emcc` image provides a complete Embscripten package.
61+
62+
For example, the following command will compile hello.c using `emcc`:
63+
64+
```
65+
$ docker run --rm -it -v `pwd`:/src apiaryio/emcc emcc hello.c
66+
```
67+
68+
The parameter `--rm` indicates that the container resource is deleted after the end of the run. The parameter `-it` indicates the standard input and output of the orientation container to the command line environment. The parameter `-v 'pwd':/src` indicates that the current directory is mapped to The /src directory of the container. The following `apiaryio/emcc` is the name of the corresponding mirror of the container, which contains the Emscripten development environment. The final emcc parameter represents the command that is running in the container, which is consistent with the local emcc command.
69+
70+
## 1.1.3 Verifying the installation
71+
72+
`emcc` is the core command of Emscripten. If the installation and activation is correct, execute `emcc -v` and you'll see version information like this:
73+
74+
```
75+
emcc -v
76+
emcc (Emscripten gcc/clang-like replacement + linker emulating GNU ld) 1.38.11
77+
clang version 6.0.1 (emscripten 1.38.11 : 1.38.11)
78+
Target: x86_64-pc-windows-msvc
79+
Thread model: posix
80+
InstalledDir: E:\Tool\emsdk\clang\e1.38.11_64bit
81+
INFO:root:(Emscripten: Running sanity checks)
82+
```
83+
84+
For more details on the installation of Emscripten, you can visit: [http://kripken.github.io/emscripten-site/docs/getting_started/downloads.html] (http://kripken.github.io/emscripten-site/ Docs/getting_started/downloads.html)
85+
86+
Emscripten has officially supported WebAssembly since v1.37.3, users who have installed older versions of Emscripten should upgrade to the latest. The contents of this book are based on Emscripten 1.38.11.

0 commit comments

Comments
 (0)