-spec env_compiler_options() -> [term()].

傳回透過環境變數 ERL_COMPILER_OPTIONS 給定的編譯器選項。如果該值是列表，則直接傳回。如果不是列表，則會放入列表中。

-spec file(module() | file:filename()) -> CompRet :: comp_ret().

與 file(File, [verbose,report_errors,report_warnings]) 相同。

-spec file(File :: module() | file:filename(), Options :: [option()] | option()) ->
              CompRet :: comp_ret().

編譯檔案 File 中的程式碼，該檔案是沒有 .erl 副檔名的 Erlang 原始碼檔案。

Options 決定編譯器的行為。

如果成功，則傳回 {ok,ModuleName}，如果發生錯誤，則傳回 error。如果編譯成功且沒有錯誤，則會建立目標碼檔案。如果原始碼中的模組名稱與輸出檔案的基底名稱不同，則視為錯誤。

可用的選項

• brief - 將錯誤和警告訊息限制為單行輸出。從 Erlang/OTP 24 開始，編譯器預設也會顯示訊息所參考的原始碼部分。

• basic_validation - 此選項是一種快速測試模組是否會成功編譯的方法。這對於想要驗證其發出的程式碼的程式碼產生器很有用。不會產生程式碼。如果啟用警告，也會傳回 erl_lint 模組產生的警告（例如，未使用的變數和函數的警告）。

  使用選項 strong_validation 產生編譯器會產生的所有警告。

• strong_validation - 與選項 basic_validation 類似。不會產生程式碼，但會執行更多編譯器階段，以確保產生最佳化階段產生的警告（例如，不會匹配的子句，或保證在執行時間因異常而失敗的運算式）。

• no_docs - 依預設，編譯器會從 文件 中提取 -doc 屬性，並根據 EEP-48 將它們放置在 Docs 區塊中。

  此選項會關閉在 Docs chunk 中放置 -doc 屬性的功能。

• binary - 編譯器會以二進制格式傳回目標碼，而不是建立目標檔案。如果成功，編譯器會傳回 {ok,ModuleName,Binary}。

• bin_opt_info - 編譯器會發出關於二進制匹配優化（無論成功或失敗）的資訊性警告。如需更多資訊，請參閱效率指南中關於 bin_opt_info 的章節。

• {compile_info, [{atom(), term()}]} - 允許基於 compile 建構的編譯器將額外的編譯元數據附加到產生的 BEAM 檔案中的 compile_info chunk。

  建議編譯器在支援 deterministic 選項且使用者已提供該選項的情況下，移除所有非決定性的資訊。

• compressed - 編譯器會壓縮產生的目標碼，這對於嵌入式系統來說很有用。

• debug_info - 在編譯後的 beam 模組的 debug_info chunk 中，以 Erlang 抽象格式的形式包含除錯資訊。Debugger、Xref 和 Cover 等工具需要包含除錯資訊。

  警告：原始碼可以從除錯資訊中重建。使用加密的除錯資訊（encrypt_debug_info）來防止這種情況。

  詳情請參閱 beam_lib(3)。

• {debug_info, {Backend, Data}} - 在編譯後的 beam 模組中，以具有自訂 Data 的 Backend 模組的形式包含自訂除錯資訊。給定的模組必須實作 debug_info/4 函數，並且負責產生不同的程式碼表示形式，如 beam_lib(3) 下的 debug_info 中所述。

  警告：原始碼可以從除錯資訊中重建。使用加密的除錯資訊（encrypt_debug_info）來防止這種情況。

• {debug_info_key,KeyString}

• {debug_info_key,{Mode,KeyString}} - 包含除錯資訊，但會將其加密，以便在不提供金鑰的情況下無法存取。（允許同時給予選項 debug_info，但並非必要。）使用此選項是在測試期間始終提供除錯資訊，同時保護原始碼的好方法。

  Mode 是用於加密除錯資訊的加密演算法類型。預設（且目前唯一）的類型是 des3_cbc。

  詳情請參閱 beam_lib(3)。

• encrypt_debug_info - 與 debug_info_key 選項類似，但金鑰是從 .erlang.crypt 檔案中讀取的。

  詳情請參閱 beam_lib(3)。

• deterministic - 省略 Module:module_info(compile) 所傳回清單中的 options 和 source 元組，並將堆疊追蹤中的路徑縮減為僅模組名稱。此選項將更容易實現可重現的建置。

• {feature, Feature, enable | disable} - 在編譯期間啟用（停用）功能 Feature。特殊功能 all 可用於啟用（停用）所有功能。

  注意

  當在 -compile(..) 屬性中使用時，此選項無效。相反地，應該使用 -feature(..) 指令（如下所述）。

  也可以使用 -feature(Feature, enable | disable). 模組指令來啟用（停用）功能。請注意，此指令只能存在於檔案的前綴中，在 exports 和函數定義之前。這是啟用和停用功能的首選方法，因為它是模組的本地屬性。

• makedep - 產生追蹤標頭相依性的 Makefile 規則。不會產生目標檔案。

  預設情況下，此規則會寫入 <File>.Pbeam。但是，如果設定了選項 binary，則不會寫入任何內容，並且規則會以 Binary 傳回。

  輸出將以 UTF-8 編碼。

  例如，如果您有以下模組

  -module(module).
  
  -include_lib("eunit/include/eunit.hrl").
  -include("header.hrl").

  此選項產生的 Makefile 規則如下所示

  module.beam: module.erl \
    /usr/local/lib/erlang/lib/eunit/include/eunit.hrl \
    header.hrl

• makedep_side_effect - 相依性會作為正常編譯過程的副作用建立。這表示也會產生目標檔案。此選項會覆寫 makedep 選項。

• {makedep_output, Output} - 將產生的規則寫入 Output，而不是預設的 <File>.Pbeam。Output 可以是檔名或 io_device()。若要寫入標準輸出，請使用 standard_io。但是，如果設定了 binary，則不會寫入任何內容到 Output，並且結果會以 {ok, ModuleName, Binary} 傳回給呼叫者。

• {makedep_target, Target} - 將發出的規則名稱變更為 Target。

• makedep_quote_target - 引號會引述 Target 中對 make(1) 來說特殊的字元。

• makedep_add_missing - 將遺失的標頭視為產生的檔案，並將其新增至相依性中。

• makedep_phony - 為每個相依性新增一個虛假的目標。

• 'P' - 在預處理和剖析轉換之後，在檔案 <File>.P 中產生剖析程式碼的清單。不會產生目標檔案。

• 'E' - 在執行所有原始碼轉換之後，在檔案 <File>.E 中產生程式碼的清單。不會產生目標檔案。

• 'S' - 在檔案 <File>.S 中產生組譯程式碼的清單。不會產生目標檔案。

• recv_opt_info - 編譯器會發出關於選擇性 receive 優化（無論成功或失敗）的資訊性警告。如需更多資訊，請參閱效率指南中關於 選擇性接收優化 的章節。

• report_errors/report_warnings - 導致在發生錯誤/警告時將其列印出來。

• report - report_errors 和 report_warnings 的簡短形式。

• return_errors - 如果設定了此旗標，則當發生錯誤時，會傳回 {error,ErrorList,WarningList}。

• return_warnings - 如果設定了此旗標，則會將包含 WarningList 的額外欄位新增至成功時傳回的元組。

• warnings_as_errors - 導致將警告視為錯誤。

• {error_location,line | column} - 如果此旗標的值為 line，則警告和錯誤的 ErrorLocation 位置為行號。如果值為 column，則 ErrorLocation 會同時包含行號和欄號。預設值為 column。此選項自 Erlang/OTP 24.0 起支援。

  如果此旗標的值為 column，則 除錯資訊 會包含欄資訊。

• return - return_errors 和 return_warnings 的簡短形式。

• verbose - 導致編譯器提供更多詳細資訊，說明它正在執行的動作。

• {source,FileName} - 覆寫 module_info(compile) 和堆疊追蹤中顯示的原始檔名。

• absolute_source - 將原始檔名（如 module_info(compile) 和堆疊追蹤中所示）轉換為絕對路徑，這有助於 perf 和 gdb 等外部工具找到 Erlang 原始程式碼。

• {outdir,Dir} - 為目標程式碼設定新的目錄。目前目錄用於輸出，除非已使用此選項指定目錄。

• export_all - 導致模組中的所有函數都被匯出。

• {i,Dir} - 將 Dir 新增至包含檔案時要搜尋的目錄清單。當遇到 -include 或 -include_lib 指令時，編譯器會在下列目錄中搜尋標頭檔

  1. "."，檔案伺服器的目前工作目錄
  2. 編譯檔案的基本名稱
  3. 使用選項 i 指定的目錄；最後指定的目錄會最先搜尋

• {d,Macro}

• {d,Macro,Value} - 將巨集 Macro 定義為具有值 Value。Macro 的類型為 atom，而 Value 可以是任何 term。預設的 Value 為 true。

• {parse_transform,Module} - 導致在檢查程式碼是否有錯誤之前，將剖析轉換函數 Module:parse_transform/2 應用於剖析程式碼。

• from_abstr - 輸入檔案預期包含以抽象格式表示表單的 Erlang term（預設檔案後綴名為 ".abstr"）。請注意，此類 term 的格式可能會在不同版本之間變更。

  另請參閱 no_lint 選項。

• from_asm - 輸入檔案預期為組譯程式碼（預設檔案後綴名為 ".S"）。請注意，組譯檔案的格式未記錄，且可能會在不同版本之間變更。

• from_core - 輸入檔案預期為核心程式碼（預設檔案後綴名為 ".core"）。請注意，核心檔案的格式未記錄，且可能會在不同版本之間變更。

• no_spawn_compiler_process - 預設情況下，所有程式碼都在單獨的程序中編譯，該程序在編譯結束時終止。但是，某些工具（如 Dialyzer 或其他 BEAM 語言的編譯器）可能已管理自己的 worker 程序，而產生額外的程序可能會降低編譯速度。在這種情況下，您可以傳遞此選項以停止編譯器產生額外的程序。

• no_strict_record_tests - 不建議使用此選項。

  預設情況下，針對操作 Record#record_tag.field 產生的程式碼會驗證元組 Record 是否具有記錄的正確大小，且第一個元素是否為標籤 record_tag。使用此選項可省略驗證碼。

• no_error_module_mismatch - 通常，編譯器會驗證原始碼中指定的模組名稱是否與輸出檔案的基本名稱相同，如果名稱不符，則會拒絕產生輸出檔案。如果模組名稱與輸出檔案名稱無關是有充分理由的，則此選項會停用該驗證（即使名稱不符也不會發出警告）。

• {no_auto_import,[{F,A}, ...]} - 使函式 F/A 不再從 erlang 模組自動匯入，這可以解決 BIF 名稱衝突的問題。當在沒有模組前綴的情況下呼叫與自動匯入的 BIF 同名的本機函式時，必須使用此選項來解決 Erlang/OTP R14A 之前就存在的自動匯入 BIF 的名稱衝突。

  如果要呼叫 BIF，請在呼叫中使用 erlang 模組前綴，而不是 {no_auto_import,[{F,A}, ...]}。

  如果此選項寫在原始碼中，作為 -compile 指令，則可以使用語法 F/A 而不是 {F,A}。例如：

  -compile({no_auto_import,[error/1]}).

• no_auto_import - 不自動從 erlang 模組匯入任何函式。

• no_line_info - 省略行號資訊以產生略小的輸出檔案。

• no_lint - 跳過檢查錯誤和警告的步驟。僅適用於與 from_abstr 選項一起使用。這主要用於在 Erlang 之上實作其他語言，這些語言已經完成了自己的檢查以保證程式碼的正確性。

  警告：當使用此選項時，無法保證編譯器輸出的程式碼是正確且可以安全使用的。程式碼正確性的責任在於產生抽象格式的程式碼或人員。如果程式碼包含錯誤，編譯器可能會崩潰或產生不安全的程式碼。

• {extra_chunks, [{binary(), binary()}]} - 傳遞額外的區塊以儲存在 .beam 檔案中。額外的區塊必須是元組列表，其中包含一個四位元組二進位制字串作為區塊名稱，後接包含區塊內容的二進位制字串。有關更多資訊，請參閱 beam_lib。

• {check_ssa, Tag :: atom()} - 解析並檢查編譯器產生的 BEAM SSA 程式碼的結構和內容的斷言。Tag 指示要檢查的斷言集，以及在哪個編譯器階段之後執行檢查。此選項是編譯器的內部選項，可以隨時更改或移除，恕不另行通知。

• line_coverage - 透過為原始碼中的每一行可執行程式碼插入 executable_line 指令來檢測編譯後的程式碼的行覆蓋率。預設情況下，載入程式碼時會忽略此指令。

  若要啟動 executable_line 指令，必須使用選項 +JPcover 啟動執行階段系統，以啟用覆蓋率模式。或者，可以使用 code:set_coverage_mode/1 在載入程式碼之前設定覆蓋率模式。

  可以透過呼叫 code:get_coverage(line, Module) 來檢索檢測後的程式碼所收集的覆蓋率資訊。

• force_line_counters - 當與選項 line_coverage 組合使用時，此模組將以 line_counter 覆蓋率模式載入，而與執行階段系統中目前的 覆蓋率模式 無關。此選項由 cover 用於載入已編譯的覆蓋率程式碼。

如果啟用了警告（如先前所述的選項 report_warnings），則以下選項會控制產生的警告類型。 除了 {warn_format,Verbosity} 之外，以下選項有兩種形式：

• 一種 warn_xxx 形式，用於開啟警告。
• 一種 nowarn_xxx 形式，用於關閉警告。

在下面的說明中，列出了用於變更預設值的形式。

• {warn_format, Verbosity} - 導致為傳遞給 io:format 和類似函式的格式字串發出格式錯誤的警告。

  Verbosity 選擇警告的數量：

  • 0 = 沒有警告
  • 1 = 無效格式字串和不正確的參數數量的警告
  • 2 = 當無法檢查有效性時（例如，當格式字串參數是變數時）也會發出警告。

  預設詳細程度為 1。也可以使用選項 nowarn_format 來選擇詳細程度 0。

• nowarn_bif_clash - 此選項已移除；如果使用會產生嚴重錯誤。

  若要解決 BIF 衝突，請使用明確的模組名稱或 {no_auto_import,[F/A]} 編譯器指令。

• {nowarn_bif_clash, FAs} - 此選項已移除；如果使用會產生嚴重錯誤。

  若要解決 BIF 衝突，請使用明確的模組名稱或 {no_auto_import,[F/A]} 編譯器指令。

• nowarn_export_all - 關閉針對 export_all 選項的使用發出的警告。預設值是在也給定選項 export_all 時發出警告。

• warn_export_vars - 對所有隱式匯出的變數發出警告，這些變數在首次定義它們的基本類型之後被引用。預設情況下，編譯器僅針對模式中引用的匯出變數發出警告。

• nowarn_shadow_vars - 關閉針對函數物件或列表推導中與已定義的變數同名的「新」變數發出的警告。預設值是針對此類變數發出警告。

• warn_keywords - 當程式碼包含在某些 功能 中用作關鍵字的 atom 時，發出警告。啟用該功能後，任何出現都將導致語法錯誤。為防止這種情況，必須重新命名或引用該 atom。

• nowarn_unused_function - 關閉針對未使用的本機函式發出的警告。預設值是針對未由匯出函式直接或間接呼叫的所有本機函式發出警告。編譯器不會在產生的 BEAM 檔案中包含未使用的本機函式，但警告對於保持原始碼的整潔仍然很有用。

• {nowarn_unused_function, FAs} - 關閉針對未使用的本機函式發出的警告，就像 nowarn_unused_function 一樣，但僅適用於提及的本機函式。FAs 是一個元組 {Name,Arity} 或此類元組的列表。

• nowarn_deprecated_function - 關閉針對呼叫已棄用函式發出的警告。預設值是針對每次呼叫編譯器已知已棄用的函式發出警告。請注意，編譯器不知道屬性 -deprecated()，而是使用 Erlang/OTP 中已棄用函式的組合列表。若要執行更全面的檢查，可以使用 Xref 工具。另請參閱 xref(3) 和函式 xref:m/1，也可以透過函式 c:xm/1 存取。

• {nowarn_deprecated_function, MFAs} - 關閉針對呼叫已棄用函式發出的警告，就像 nowarn_deprecated_function 一樣，但僅適用於提及的函式。MFAs 是一個元組 {Module,Name,Arity} 或此類元組的列表。

• nowarn_deprecated_type - 關閉針對使用已棄用類型發出的警告。預設值是針對每次使用編譯器已知已棄用的類型發出警告。

• nowarn_deprecated_callback - 關閉針對使用已棄用回呼發出的警告。預設值是針對每次使用編譯器已知已棄用的回呼發出警告。

• nowarn_removed - 關閉針對呼叫已移除函式發出的警告。預設值是針對每次呼叫編譯器已知最近已從 Erlang/OTP 中移除的函式發出警告。

• {nowarn_removed, ModulesOrMFAs} - 關閉針對呼叫已移除的模組或函式發出的警告。預設值是針對每次呼叫編譯器已知最近已從 Erlang/OTP 中移除的函式發出警告。

• nowarn_obsolete_guard - 關閉針對呼叫舊式類型測試 BIF（例如 pid/1 和 list/1）發出的警告。有關類型測試 BIF 及其舊式等效項的完整列表，請參閱 Erlang 參考手冊。預設值是針對呼叫舊式類型測試 BIF 發出警告。

• warn_unused_import - 針對未使用的匯入函式發出警告。預設值是不針對未使用的匯入函式發出警告。

• nowarn_underscore_match - 預設情況下，當綁定後比對以底線開頭的變數時，會發出警告。使用此選項可以關閉此類警告。

• nowarn_unused_vars - 預設情況下，會針對未使用的變數發出警告，但以底線開頭的變數（「Prolog 風格警告」）除外。使用此選項可以關閉此類警告。

• nowarn_unused_record - 關閉針對未使用的記錄定義發出的警告。預設值是針對未使用的本機定義記錄發出警告。

• {nowarn_unused_record, RecordNames} - 關閉針對未使用的記錄定義發出的警告。預設值是針對未使用的本機定義記錄發出警告。

• nowarn_unused_type - 關閉針對未使用的類型宣告發出的警告。預設值是針對未使用的本機類型宣告發出警告。

• nowarn_nif_inline - 預設情況下，當在可能載入 NIF 的模組中啟用內聯時，會發出警告，因為編譯器可能會意外地內聯 NIF 後備機制。使用此選項可以關閉此類警告。

• warn_missing_doc | warn_missing_doc_functions | warn_missing_doc_types | warn_missing_doc_callbacks
  預設情況下，當導出函式、回呼函式或類型的 -doc 屬性未給定時，不會發出警告。使用這些選項來開啟此類警告。warn_missing_doc 等同於設定所有 warn_missing_doc_functions、warn_missing_doc_types 和 warn_missing_doc_callbacks。

• nowarn_missing_doc | nowarn_missing_doc_functions | nowarn_missing_doc_types | nowarn_missing_doc_callbacks
  如果警告是由 warn_missing_doc 啟用，則可以使用這些選項再次關閉這些警告。nowarn_missing_doc 等同於設定所有 nowarn_missing_doc_functions、nowarn_missing_doc_types 和 nowarn_missing_doc_callbacks。

• nowarn_hidden_doc | {nowarn_hidden_doc,NAs}
  預設情況下，當在回呼函式或參考類型上設定 -doc false 屬性時，會發出警告。您可以設定 nowarn_hidden_doc 來抑制所有這些警告，或者設定 {nowarn_hidden_doc, NAs} 來抑制特定的回呼函式或類型。NAs 是一個元組 {Name, Arity} 或此類元組的列表。

• warn_missing_spec - 預設情況下，當未給出導出函式的規格（或合約）時，不會發出警告。使用此選項來開啟此類警告。

• warn_missing_spec_documented - 預設情況下，當未給出已記錄函式的規格（或合約）時，不會發出警告。使用此選項來開啟此類警告。

• warn_missing_spec_all - 預設情況下，當未給出導出或未導出函式的規格（或合約）時，不會發出警告。使用此選項來開啟此類警告。

• nowarn_redefined_builtin_type - 預設情況下，當本地重新定義內建類型時，會發出警告。使用此選項來關閉此類警告。

• {nowarn_redefined_builtin_type, Types} - 預設情況下，當本地重新定義內建類型時，會發出警告。使用此選項來關閉 Types 中類型的此類警告，其中 Types 是一個元組 {TypeName,Arity} 或此類元組的列表。

其他種類的警告是機會主義警告。它們是在編譯器在最佳化和程式碼產生期間碰巧注意到潛在問題時產生的。

注意

編譯器不會針對它不嘗試最佳化的表達式發出警告。例如，編譯器會針對 1/0 發出警告，但不會針對 X/0 發出警告，因為 1/0 是一個編譯器會嘗試評估的常數表達式。

沒有警告並不表示程式碼中沒有剩餘錯誤。

可以使用以下選項停用機會主義警告

• nowarn_opportunistic - 停用所有機會主義警告。

• nowarn_failed - 停用永遠會失敗的表達式的警告（例如 atom+42）。

• nowarn_ignored - 停用其值被忽略的表達式的警告。

• nowarn_nomatch - 停用永遠不會匹配的模式（例如 a=b）和永遠評估為 false 的守衛的警告。

注意

所有選項，除了包含路徑（{i,Dir}），也可以在檔案中使用屬性 -compile([Option,...]) 給定。屬性 -compile() 允許在函式定義之後使用。

注意

在 Erlang/OTP 22 之前，選項 {nowarn_deprecated_function, MFAs} 只有在使用屬性 -compile() 在檔案中給定時才被識別。（選項 {nowarn_unused_function,FAs} 被錯誤地記錄為僅在檔案中有效，但它在選項列表中給定時也有效。）從 Erlang/OTP 22 開始，可以在檔案中給定的所有選項也可以在選項列表中給定。

為了除錯編譯器，或純粹出於好奇，可以檢查每個編譯器階段產生的中間程式碼。若要列印產生列表檔案的完整選項列表，請在 Erlang shell 提示字元輸入 compile:options()。這些選項會按照階段執行的順序列印。如果使用多個列表選項，則代表最早階段的選項會生效。

無法識別的選項將被忽略。

WarningList 和 ErrorList 都具有以下格式

[{FileName,[ErrorInfo]}].

此處包含檔案名稱，因為編譯器使用 Erlang 前處理器 epp，它允許將程式碼包含在其他檔案中。因此，務必了解錯誤或警告的位置指的是哪個檔案。

ErrorInfo 結構具有以下格式

{ErrorLocation, Module, ErrorDescriptor}

ErrorLocation 通常是元組 {Line, Column}。如果已給定選項 {error_location,line}，則 ErrorLocation 僅為行號。如果錯誤不對應於特定位置（例如，如果原始程式檔不存在），則 ErrorLocation 為原子 none。

描述錯誤的字串可以使用以下呼叫取得

Module:format_error(ErrorDescriptor)

-spec format_error(ErrorDescription :: error_description()) -> string().

使用 ErrorDescriptor 並傳回描述錯誤的深層字元列表。

當處理 ErrorInfo 結構時，通常會隱式呼叫此函式。

-spec forms(forms()) -> CompRet :: comp_ret().

與 forms(Forms, [verbose,report_errors,report_warnings]) 相同。

-spec forms(Forms :: forms(), Options :: [option()] | option()) -> CompRet :: comp_ret().

類似於 file/1，但將表單列表（以 Erlang 抽象或 Core Erlang 格式表示）作為第一個引數。

選項 binary 是隱式的，也就是說，不會產生物件程式碼檔案。對於通常會產生列表檔案的選項（例如 'E'），會傳回該編譯器階段的內部格式（Erlang 詞彙，通常不是二進制），而不是二進制。

-spec noenv_file(File :: module() | file:filename(), Options :: [option()] | option()) -> comp_ret().

運作方式與 file/2 類似，但不會查詢環境變數 ERL_COMPILER_OPTIONS。

-spec noenv_forms(Forms :: forms(), Options :: [option()] | option()) -> comp_ret().

運作方式與 forms/2 類似，但不會查詢環境變數 ERL_COMPILER_OPTIONS。

-spec noenv_output_generated(Options :: [option()]) -> boolean().

運作方式與 output_generated/1 類似，但不會查詢環境變數 ERL_COMPILER_OPTIONS。

-spec output_generated(Options :: [option()]) -> boolean().

決定編譯器是否使用給定的選項產生 BEAM 檔案。

true 表示會產生 BEAM 檔案。false 表示編譯器會產生一些列表檔案、傳回二進制，或僅檢查原始程式碼的語法。