Emscripten教程之emcc編譯命令

emcc(Emscripten Compiler Frontend)介紹

翻譯：雲荒杯傾
本文是Emscripten-WebAssembly專欄系列文章之一，更多文章請查看專欄。
也能夠去做者的博客閱讀文章。
歡迎加入Wasm和emscripten技術交流羣，羣聊號碼：939206522。

emcc用於從命令行調用Emscripten的編譯器，它其實是標準編譯器gcc或者clang的一個替換。

語法

---

emcc [options] file ...

這個輸入文件file，既能夠是clang能夠編譯的C/C++語言，也能夠是二進制形式的llvm bitcode或者人類可讀形式的llvm assembly文件。

參數

大部分clang或者gcc的選項（option）都是能夠工做的，好比：

# 顯示信息
emcc --help
# 顯示編譯器版本信息
emcc --version

若是想看當前Emscripten中clang版本支持的所有選項列表，能夠直接使用命令：
clang --help.

emcc修改的或者emcc中新的選項列在下面：

首先是一些編譯優化flag，它們-O0，-O1，-O2，-Os，-Oz，-O3。

-O0：
不進行編譯優化（這是默認狀況）。當你剛開始移植項目是推薦使用它，由於它會包含許多斷言。

-O1：
簡單優化。推薦你在既想縮短編譯時間又想編譯優化時使用。它畢竟比-O2級別的優化編譯起來快多了。它會進行asm.js和llvm的-O1進行優化，它會relooping，會刪除運行時斷言和C++異常捕獲，它也會使得-s ALIASING_FUNCTION_POINTERS=1。

想要C++異常捕獲從新可用，請設置：-s DISABLE_EXCEPTION_CATCHING=0。

-O2：
和-O1相似，不過多了JavaScript級別的優化以及一些llvm -O3的優化項。當你想發佈項目的時候，推薦使用本級別優化。

-O3：
和-O2相似，不過比-O2又多了一些JavaScript優化，並且編譯時間明顯比-O2長。這個也推薦在發佈版本的時候使用。

-Os:
和-O3相似，不過增長了額外的優化以減少生成的代碼體積，代價是比-O3性能差一點。-Os優化會同時影響llvm bitcode 和JavaScript文件的生成。

-Oz:
和-Os相似，不過進一步減少了代碼體積。

-s OPTION=VALUE
傳給編譯器的全部涉及到JavaScript代碼生成的選項。選項列表，請見settings.js。

對於某個選項的值，不只能夠直接在emcc命令行裏面設定，也能夠把他們寫成json文件。好比下面，就是將DEAD_FUNCTIONS選項的值放到了path/to/file文件裏，emcc裏面傳這個文件的路徑。

-s DEAD_FUNCTIONS=@/path/to/file

note:
一、文件內容能夠是：["_func1","_func2"]；
二、文件路徑必須是絕對的，不能是相對的。

-g：
這是保留調試信息flag。

• 若是隻是編譯到bitcode，那就和clang和gcc中的-g同樣。
• 若是是要編譯到JavaScript，-g就等於-g3。

-g<level>
控制打印的調試信息數量，每個level都是在前一個level的基礎上編譯的：

• -g0:不保留調試信息。
• -g1:保留空格,不壓縮。
• -g2:保留函數名。
• -g3:保留變量名，與-g同。變量名通常不是必須編譯後保留的，可是若是保留了，能夠推斷變量的目的，對吧。
• -g4:保留llvm 調試信息，這是能調試的最高級別。

note：
優化級別越高，編譯時間越長

--profiling:

--profiling-funcs:

--tracing:
啓用Emscripten的tracing API。

--emit-symbol-map：

--js-opts<level>:
容許JavaScript優化，有兩個值：
0：不容許JavaScript優化器容許；
1：使用JavaScript優化器。
一般用不到咱們設置這一項， 由於設置-O後面的level的時候，這個項就能順便取到一個合適的值。

note：
有些選項會重寫這個flag的值，好比EMTERPRETIFY, DEAD_FUNCTIONS, OUTLINING_LIMIT, SAFE_HEAP 和 SPLIT_MEMORY會將js-opts=1，由於他們依賴js優化器。

--llvm-opts<level>:
啓用llvm優化。它的取值有有：

• 0：不使用llvm優化
• 1：llvm -O1優化
• 2：llvm -O2優化
• 3：llvm -O3優化

和--js-opts<level>同樣，一般用不到咱們設置這一項， 由於設置-O後面的level的時候，這個項就能順便取到一個合適的值。

--llvm-lto<level>:
啓用llvm 鏈接時 優化。能夠取值0，1，2，3。

--closure <on>：
運行壓縮編譯器（Closure Compiler），可能的取值有，0,1,2：

• 0：是不啓用壓縮編譯器。
• 1：啓用。
• 2：啓用。

--pre-js <file>
生成代碼前，指定一個要把內容添加進來的文件。

--post-js <file>
生成代碼後，指定一個要把內容添加進來的文件。

--embed-file <file>
指定一個帶路徑的文件嵌入到編譯生成的js代碼裏。路徑是相對於編譯時的當前路徑。若是傳的是一個目錄，則目錄下全部文件的內容都會被嵌入到未來生成的js代碼中。

--preload-file <name>
異步運行編譯代碼前，指定一個預加載的文件。路徑是相對於編譯時的當前路徑。若是傳的是一個目錄，則目錄下全部文件的內容都會被預加載到一個.data文件中。

--exclude-file <name>
從 –embed-file and –preload-file後面的目錄中排除一些文件，支持使用通配符*。

--use-preload-plugins
告訴文件打包器當文件加載時，運行預加載插件。它用來執行諸如使用瀏覽器解碼器解碼圖片和音頻等。

--shell-file <path>
指定要生成HTML的模板文件。

--source-map-base <base-url>

--minify 0
等於-g1。

--js-transform <cmd>
優化以前，生成代碼以後，設定這一條命令。這條命令可讓你修改JavaScript代碼。以後，編譯器會將修改的和未修改的一塊兒進行編譯優化。

--bind
啓用bingdings編譯源代碼。bingings是Emscripten中鏈接C++和JavaScript代碼的一類API。

--ignore-dynamic-linking
告訴編譯器忽視動態連接，以後用戶就得手動連接到共享庫。

--js-library <lib>
定義除了核心庫(src/library_*)之外的js庫。

-v
打開詳細輸出。
這個設置爲把-v傳給clang，而且啓用EMCC_DEBUG生成編譯階段的中間文件。它也會運行Emscripten關於工具鏈的內部的完整性檢查。

tip:
emcc -v是診斷錯誤的有用工具，無論你是否附加其餘參數。

--cache

--clear-cache

--clear-ports

--show-ports

--save-bc PATH

--memory-init-file <on>
規定是否單獨生成一個內存初始化文件。取值包括0和1.

• 0：不單獨生成.mem文件。
• 1：單獨生成.mem文件。

-Wwarn-absolute-paths
啓用在-I和-L命令行指令中使用絕對路徑的警告。這是用來警告無心中使用了絕對路徑的。在引用非可移植的本地系統頭文件時，使用絕對路徑有時是很危險的。

--proxy-to-worker

--emrun
使生成的代碼可以感知emrun命令行工具。當運行emran生成的應用程序時，這樣設置就容許stdout、stderr和exit(returncode)被捕獲。

--cpuprofiler
在生成的頁面上嵌入一個簡單的CPU分析器。使用這個來執行粗略的交互式性能分析。

--memoryprofiler
在生成的頁面上嵌入內存分配跟蹤器，使用它來分析應用程序Emscripten堆的使用狀況。

--threadprofiler
在生成的頁面上嵌入一個線程活動分析器。當進行多線程編譯時，使用它來分析多線程應用程序。
--em-config

--default-obj-ext .ext

--valid-abspath path
設置一個絕對路徑的白名單，以防止關於絕對路徑的警告。

-o <target>
編譯輸出的文件格式。target能夠取值爲：

• name.js:JavaScript文件；
• name.html：HTML+js文件。把js單獨生成是爲了減少頁面加載時間。
• name.bc：llvm bitcode。這是默認值。
• name.o：和上面同樣。

note:
若是你用了--memory-init-file，則還會從js文件中再單獨分出一部分代碼爲.mem文件。

-c
生成llvm bitcode代碼，而不是JavaScript。

--separate-asm
把asm.js文件單獨生成到一個文件中。這樣能夠減小啓動時的內存加載。

--output_eol windows|linux
規定生成的文本文件的行尾，若是是–output_eol windows，就是windows rn行尾，若是是–output_eol linux，則生成Linux行尾的文本文件。

--cflags

環境變量

---

emcc會受到幾個環境變量的影響，以下：

• EMMAKEN_JUST_CONFIGURE
• EMMAKEN_JUST_CONFIGURE_RECURSE
• EMCONFIGURE_JS
• EMCONFIGURE_CC
• EMMAKEN_CXX
• EMMAKEN_COMPILER
• EMMAKEN_CFLAGS
• EMCC_DEBUG

這幾個裏面比較有意思的是EMCC_DEBUG。好比，若是你在編譯以前設置set EMCC_DEBUG=1，那麼編譯的時候會把編譯過程的調試信息和編譯各個階段的中間文件輸出到一個臨時目錄，這算是給開發者提供一些編譯期間的幫助或者說調試信息吧。

---

Emscripten主題系列文章是emscripten中文站點的一部份內容。
第一個主題介紹代碼可移植性與限制
第二個主題介紹Emscripten的運行時環境
第三個主題第一篇文章介紹鏈接C++和JavaScript
第三個主題第二篇文章介紹embind
第四個主題介紹文件和文件系統
第六個主題介紹Emscripten如何調試代碼