-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 中的代码，该文件是 Erlang 源代码文件，不带 .erl 扩展名。

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 块中放置 -doc 属性。

• binary - 编译器以二进制形式返回目标代码，而不是创建目标文件。如果成功，编译器将返回 {ok,ModuleName,Binary}。

• bin_opt_info - 编译器将发出关于二进制匹配优化（成功和不成功）的信息性警告。 更多信息，请参阅效率指南中关于 bin_opt_info 的部分。

• {compile_info, [{atom(), term()}]} - 允许在 compile 之上构建的编译器将额外的编译元数据附加到生成的 BEAM 文件中的 compile_info 代码块中。

  建议编译器在支持 deterministic 选项且用户提供了该选项时，删除所有不确定的信息。

• compressed - 编译器将压缩生成的对象代码，这对于嵌入式系统很有用。

• debug_info - 在已编译的 beam 模块的 debug_info 代码块中，以 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). 模块指令来启用（禁用）特性。 请注意，此指令只能存在于文件的前缀中，在导出和函数定义之前。 这是启用和禁用特性的首选方法，因为它是一个模块的本地属性。

• 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()。 要写入 stdout，请使用 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 的类型为原子，Value 可以是任何项。 默认 Value 为 true。

• {parse_transform,Module} - 使解析转换函数 Module:parse_transform/2 在检查代码是否有错误之前应用于解析后的代码。

• from_abstr - 输入文件应包含表示抽象格式的形式的 Erlang 项（默认文件后缀为“.abstr”）。 请注意，此类项的格式可能在不同版本之间发生变化。

  另请参阅 no_lint 选项。

• from_asm - 输入文件应为汇编代码（默认文件后缀为“.S”）。 请注意，汇编文件的格式没有文档记录，并且可能在不同版本之间发生变化。

• from_core - 输入文件应为核心代码（默认文件后缀为“.core”）。 请注意，核心文件的格式没有文档记录，并且可能在不同版本之间发生变化。

• no_spawn_compiler_process - 默认情况下，所有代码都在单独的进程中编译，该进程在编译结束时终止。 但是，某些工具（如 Dialyzer 或其他 BEAM 语言的编译器）可能已经管理了自己的工作进程，并且生成额外的进程可能会减慢编译速度。 在这种情况下，您可以传递此选项以阻止编译器生成额外的进程。

• no_strict_record_tests - 不建议使用此选项。

  默认情况下，为操作 Record#record_tag.field 生成的代码会验证元组 Record 是否具有记录的正确大小，并且第一个元素是否为标签 record_tag。 使用此选项可以省略验证代码。

• no_error_module_mismatch - 通常，编译器会验证源代码中给出的模块名称是否与输出文件的基本名称相同，如果存在不匹配，则拒绝生成输出文件。 如果有充分的理由使模块名称与输出文件的名称无关，则此选项将禁用该验证（如果存在不匹配，则甚至不会发出警告）。

• {no_auto_import,[{F,A}, ...]} - 使函数 F/A 不再从 erlang 模块自动导入，从而解决 BIF 名称冲突。 此选项必须用于解决与 Erlang/OTP R14A 之前存在的自动导入的 BIF 的名称冲突，当时在不带模块前缀的情况下调用与自动导入的 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 文件中。额外的块必须是元组列表，其中包含一个 4 字节的二进制文件作为块名称，后跟一个包含块内容的二进制文件。有关更多信息，请参阅 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 - 当代码包含在某些 功能中用作关键字的原子时，发出警告。启用该功能后，任何出现都会导致语法错误。为了防止这种情况，必须重命名或引用该原子。

• 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 - 默认情况下，当在绑定后匹配以 underscore 开头的变量时，会发出警告。使用此选项关闭此类警告。

• nowarn_unused_vars - 默认情况下，会为未使用的变量发出警告，但以 underscore 开头的变量除外（“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 的 guard 的警告。

注意

所有选项，除了包含路径 ({i,Dir}) 之外，也可以在文件中使用属性 -compile([Option,...]) 来指定。函数定义之后允许使用属性 -compile()。

注意

在 Erlang/OTP 22 之前，只有在文件中使用属性 -compile() 指定时，才会识别选项 {nowarn_deprecated_function, MFAs}。(选项 {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 表示编译器生成一些列表文件，返回二进制文件，或者仅检查源代码的语法。