Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
compile(3)		   Erlang Module Definition		    compile(3)

NAME
       compile - Erlang	Compiler

DESCRIPTION
       This  module  provides an interface to the standard Erlang compiler. It
       can generate either a new file which contains the object	code,  or  re-
       turn a binary which can be loaded directly.

EXPORTS
       file(File)

	      Is  the  same  as	file(File, [verbose,report_errors,report_warn-
	      ings]).

       file(File, Options) -> CompRet

	      Types:

		 CompRet = ModRet | BinRet | ErrRet
		 ModRet	= {ok,ModuleName} | {ok,ModuleName,Warnings}
		 BinRet	= {ok,ModuleName,Binary} | {ok,ModuleName,Binary,Warn-
		 ings}
		 ErrRet	= error	| {error,Errors,Warnings}

	      Compiles	the  code  in the file File, which is an Erlang	source
	      code file	without	the .erl extension. Options determine the  be-
	      havior of	the compiler.

	      Returns {ok,ModuleName} if successful, or	error if there are er-
	      rors. An object code file	is created if the compilation succeeds
	      with  no	errors.	 It is considered to be	an error if the	module
	      name in the source code is not the same as the basename  of  the
	      output file.

	      Here follows first all elements of Options that in some way con-
	      trol the behavior	of the compiler.

		basic_validation:
		  This option is fast way to test whether a module  will  com-
		  pile	successfully  (mainly  useful for code generators that
		  want to verify the code they emit). No code will  generated.
		  If  warnings are enabled, warnings generated by the erl_lint
		  module (such as warnings for unused variables	and functions)
		  will be returned too.

		  Use  the  strong_validation  option to generate all warnings
		  that the compiler would generate.

		strong_validation:
		  Similar to the basic_validation option, no code will be gen-
		  erated,  but more compiler passes will be run	to ensure also
		  warnings generated by	the optimization passes	are  generated
		  (such	as clauses that	will not match or expressions that are
		  guaranteed to	fail with an exception at run-time).

		binary:
		  Causes the compiler to return	the object code	 in  a	binary
		  instead  of creating an object file. If successful, the com-
		  piler	returns	{ok,ModuleName,Binary}.

		bin_opt_info:
		  The compiler will emit informational warnings	 about	binary
		  matching  optimizations  (both successful and	unsuccessful).
		  See the Efficiency Guide for further information.

		compressed:
		  The compiler will compress the generated object code,	 which
		  can be useful	for embedded systems.

		debug_info:

		  Include  debug information in	the form of abstract code (see
		  The Abstract Format in ERTS User's Guide)  in	 the  compiled
		  beam	module.	Tools such as Debugger,	Xref and Cover require
		  the debug information	to be included.

		  Warning: Source code can be reconstructed from the debug in-
		  formation.  Use  encrypted  debug information	(see below) to
		  prevent this.

		  See beam_lib(3) for details.

		{debug_info_key,KeyString}:

		{debug_info_key,{Mode,KeyString}}:

		  Include debug	information, but encrypt it, so	that it	cannot
		  be  accessed	without	 supplying  the	 key. (To give the de-
		  bug_info option as well is allowed, but is  not  necessary.)
		  Using	this option is a good way to always have the debug in-
		  formation available during testing, yet protect  the	source
		  code.

		  Mode is the type of crypto algorithm to be used for encrypt-
		  ing the debug	information. The default type -- and currently
		  the only type	-- is des3_cbc.

		  See beam_lib(3) for details.

		encrypt_debug_info:

		  Like	the  debug_info_key  option above, except that the key
		  will be read from an .erlang.crypt file.

		  See beam_lib(3) for details.

		makedep:
		  Produce a Makefile rule to track  headers  dependencies.  No
		  object file is produced.

		  By  default,	this rule is written to	_File_.Pbeam. However,
		  if the option	binary is set, nothing is written and the rule
		  is returned in Binary.

		  For instance,	if one has the following module:

		-module(module).

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

		  Here is the Makefile rule generated by this option:

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

		{makedep_output, Output}:
		  Write	 generated  rule(s)  to	 Output	instead	of the default
		  _File_.Pbeam.	Output can be a	filename or an io_device(). To
		  write	 to stdout, use	standard_io. However if	binary is set,
		  nothing is written to	Output and the result is  returned  to
		  the caller with {ok, ModuleName, Binary}.

		{makedep_target, Target}:
		  Change the name of the rule emitted to Target.

		makedep_quote_target:
		  Characters in	Target special to make(1) are quoted.

		makedep_add_missing:
		  Consider  missing headers as generated files and add them to
		  the dependencies.

		makedep_phony:
		  Add a	phony target for each dependency.

		'P':
		  Produces a listing of	the parsed  code  after	 preprocessing
		  and  parse  transforms, in the file _File_.P.	No object file
		  is produced.

		'E':
		  Produces a listing of	the code after all source code	trans-
		  formations have been performed, in the file _File_.E.	No ob-
		  ject file is produced.

		'S':
		  Produces a  listing  of  the	assembler  code	 in  the  file
		  _File_.S. No object file is produced.

		report_errors/report_warnings:
		  Causes errors/warnings to be printed as they occur.

		report:
		  This is a short form for both	report_errors and report_warn-
		  ings.

		return_errors:
		  If this flag is set, then  {error,ErrorList,WarningList}  is
		  returned when	there are errors.

		return_warnings:
		  If  this  flag  is set, then an extra	field containing Warn-
		  ingList is added to the tuples returned on success.

		warnings_as_errors:
		  Causes warnings to be	treated	as errors. This	option is sup-
		  ported since R13B04.

		return:
		  This is a short form for both	return_errors and return_warn-
		  ings.

		verbose:
		  Causes more verbose information from the compiler describing
		  what it is doing.

		{source,FileName}:
		  Sets	 the   value  of  the  source,	as  returned  by  mod-
		  ule_info(compile).

		{outdir,Dir}:
		  Sets a new directory for the object code. The	current	direc-
		  tory	is  used  for output, except when a directory has been
		  specified with this option.

		export_all:
		  Causes all functions in the module to	be exported.

		{i,Dir}:
		  Add Dir to the list of directories to	be searched  when  in-
		  cluding  a  file.  When  encountering	 an  -include  or -in-
		  clude_lib directive, the compiler searches for header	 files
		  in the following directories:

		  * ".", the current working directory of the file server;

		  * the	base name of the compiled file;

		  * the	 directories  specified	using the i option. The	direc-
		    tory specified last	is searched first.

		{d,Macro}:

		{d,Macro,Value}:
		  Defines a macro Macro	to have	the value Value. Macro	is  of
		  type	atom,  and Value can be	any term. The default Value is
		  true.

		{parse_transform,Module}:
		  Causes the parse transformation function Module:parse_trans-
		  form/2  to  be applied to the	parsed code before the code is
		  checked for errors.

		from_asm:
		  The input file is expected to	 be  assembler	code  (default
		  file	suffix	".S"). Note that the format of assembler files
		  is not documented, and may change between releases.

		from_core:
		  The input file is expected to	be  core  code	(default  file
		  suffix  ".core").  Note that the format of core files	is not
		  documented, and may change between releases.

		no_strict_record_tests:
		  This option is not recommended.

		  By	default,    the	    generated	  code	   for	   the
		  Record#record_tag.field  operation  verifies	that the tuple
		  Record is of the correct size	for the	record	and  that  the
		  first	element	is the tag record_tag. Use this	option to omit
		  the verification code.

		no_error_module_mismatch:
		  Normally the compiler	verifies that the module name given in
		  the  source  code is the same	as the base name of the	output
		  file and refuses to generate an output file if  there	 is  a
		  mismatch.  If	 you  have a good reason (or other reason) for
		  having a module name unrelated to the	 name  of  the	output
		  file,	this option disables that verification (there will not
		  even be a warning if there is	a mismatch).

		{no_auto_import,[{F,A},	...]}:
		  Makes	the function F/A no longer  being  auto-imported  from
		  the module erlang, which resolves BIF	name clashes. This op-
		  tion has to be used to resolve name clashes with BIFs	 auto-
		  imported  before  R14A, if one wants to call the local func-
		  tion with the	same name as an	auto-imported BIF without mod-
		  ule prefix.

	    Note:
		From  R14A  and	 forward,  the compiler	resolves calls without
		module prefix to local or  imported  functions	before	trying
		auto-imported BIFs. If the BIF is to be	called,	use the	erlang
		module prefix in the call, not { no_auto_import,[{F,A},	...]}

		  If this option is written in the source code,	as a  -compile
		  directive,  the syntax F/A can be used instead of {F,A}. Ex-
		  ample:

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

		no_auto_import:
		  Do not auto import any functions from	the module erlang.

		no_line_info:
		  Omit line number information in order	to produce a  slightly
		  smaller output file.

	      If  warnings are turned on (the report_warnings option described
	      above), the following options control what type of warnings that
	      will be generated. With the exception of {warn_format,Verbosity}
	      all options below	have two forms;	one warn_xxx form to  turn  on
	      the  warning and one nowarn_xxx form to turn off the warning. In
	      the description that follows, the	form that is  used  to	change
	      the default value	is listed.

		{warn_format, Verbosity}:
		  Causes  warnings  to be emitted for malformed	format strings
		  as arguments to io:format and	similar	 functions.  Verbosity
		  selects  the	amount of warnings: 0 =	no warnings; 1 = warn-
		  ings for invalid format strings and incorrect	number of  ar-
		  guments;  2  =  warnings also	when the validity could	not be
		  checked (for example,	when the format	string argument	 is  a
		  variable).  The default verbosity is 1. Verbosity 0 can also
		  be selected by the option nowarn_format.

		nowarn_bif_clash:
		  This option is removed, it will generate a  fatal  error  if
		  used.

	    Warning:
		Beginning with R14A, the compiler no longer calls the auto-im-
		ported BIF if the name clashes with a local or explicitly  im-
		ported function	and a call without explicit module name	is is-
		sued. Instead the local	or imported function is	called.	 Still
		accepting  nowarn_bif_clash would makes	a module calling func-
		tions clashing with autoimported BIFs compile  with  both  the
		old  and  new  compilers, but with completely different	seman-
		tics, why the option was removed.

		The use	of this	option has always been	strongly  discouraged.
		From OTP R14A and forward it's an error	to use it.

		To  resolve  BIF  clashes,  use	 explicit  module names	or the
		{no_auto_import,[F/A]} compiler	directive.

		{nowarn_bif_clash, FAs}:
		  This option is removed, it will generate a  fatal  error  if
		  used.

	    Warning:
		The  use  of this option has always been strongly discouraged.
		From OTP R14A and forward it's an error	to use it.

		To resolve BIF clashes,	 use  explicit	module	names  or  the
		{no_auto_import,[F/A]} compiler	directive.

		warn_export_all:
		  Causes  a warning to be emitted if the export_all option has
		  also been given.

		warn_export_vars:
		  Causes warnings to be	emitted	for  all  implicitly  exported
		  variables  referred  to after	the primitives where they were
		  first	defined. No warnings  for  exported  variables	unless
		  they	are referred to	in some	pattern, which is the default,
		  can be selected by the option	nowarn_export_vars.

		warn_shadow_vars:
		  Causes warnings to be	emitted	for "fresh" variables in func-
		  tional  objects or list comprehensions with the same name as
		  some already defined variable. The default is	 to  warn  for
		  such	variables.  No	warnings for shadowed variables	can be
		  selected by the option nowarn_shadow_vars.

		nowarn_unused_function:
		  Turns	off warnings for unused	local  functions.  By  default
		  (warn_unused_function),  warnings  are emitted for all local
		  functions that are not called	directly or indirectly	by  an
		  exported  function. The compiler does	not include unused lo-
		  cal functions	in the generated beam file, but	the warning is
		  still	useful to keep the source code cleaner.

		{nowarn_unused_function, FAs}:
		  Turns	 off warnings for unused local functions as nowarn_un-
		  used_function	but only for the  mentioned  local  functions.
		  FAs is a tuple {Name,Arity} or a list	of such	tuples.

		nowarn_deprecated_function:
		  Turns	off warnings for calls to deprecated functions.	By de-
		  fault	(warn_deprecated_function), warnings are  emitted  for
		  every	 call to a function known by the compiler to be	depre-
		  cated. Note that the compiler	does not know about the	 -dep-
		  recated() attribute but uses an assembled list of deprecated
		  functions in Erlang/OTP. To do a more	general	check the Xref
		  tool can be used. See	also xref(3) and the function xref:m/1
		  also accessible through the c:xm/1 function.

		{nowarn_deprecated_function, MFAs}:
		  Turns	off warnings for  calls	 to  deprecated	 functions  as
		  nowarn_deprecated_function  but only for the mentioned func-
		  tions. MFAs is a tuple {Module,Name,Arity} or	a list of such
		  tuples.

		nowarn_deprecated_type:
		  Turns	 off warnings for uses of deprecated types. By default
		  (warn_deprecated_type), warnings are emitted for  every  use
		  of a type known by the compiler to be	deprecated.

		warn_obsolete_guard:
		  Causes  warnings to be emitted for calls to old type testing
		  BIFs such as pid/1 and list/1. See the Erlang	Reference Man-
		  ual  for  a complete list of type testing BIFs and their old
		  equivalents. No warnings for calls to	old type testing BIFs,
		  which	 is  the  default,  can	 be  selected  by  the	option
		  nowarn_obsolete_guard.

		warn_unused_import:
		  Causes warnings to be	emitted	for unused imported functions.
		  No  warnings for unused imported functions, which is the de-
		  fault, can be	selected by the	option nowarn_unused_import.

		nowarn_unused_vars:
		  By default, warnings are emitted for variables which are not
		  used,	 with the exception of variables beginning with	an un-
		  derscore ("Prolog style warnings"). Use this option to  turn
		  off this kind	of warnings.

		nowarn_unused_record:
		  Turns	 off  warnings	for  unused  record  types. By default
		  (warn_unused_records), warnings are emitted for  unused  lo-
		  cally	defined	record types.

	      Another  class  of  warnings is generated	by the compiler	during
	      optimization and code generation.	They warn about	patterns  that
	      will never match (such as	a=b), guards that will always evaluate
	      to false,	 and  expressions  that	 will  always  fail  (such  as
	      atom+42).

	      Note  that  the  compiler	 does not warn for expressions that it
	      does not attempt to optimize. For	instance, the  compiler	 tries
	      to  evaluate  1/0,  notices  that	it will	cause an exception and
	      emits a warning. On the other hand, the compiler is silent about
	      the  similar  expression X/0; because of the variable in it, the
	      compiler does not	even try to evaluate and therefore it emits no
	      warnings.

	      Currently,  those	 warnings  cannot  be disabled (except by dis-
	      abling all warnings).

	  Warning:
	      Obviously, the absence of	warnings does not mean that there  are
	      no remaining errors in the code.

	      Note  that all the options except	the include path ({i,Dir}) can
	      also be given in the file	with a -compile([Option,...]).	attri-
	      bute. The	-compile() attribute is	allowed	after function defini-
	      tions.

	      Note    also    that    the    {nowarn_unused_function,	 FAs},
	      {nowarn_bif_clash,  FAs},	and {nowarn_deprecated_function, MFAs}
	      options are only recognized when given in	files.	They  are  not
	      affected	 by   the   warn_unused_function,  warn_bif_clash,  or
	      warn_deprecated_function options.

	      For debugging of the compiler, or	for pure curiosity, the	inter-
	      mediate code generated by	each compiler pass can be inspected. A
	      complete list of the  options  to	 produce  list	files  can  be
	      printed  by typing compile:options() at the Erlang shell prompt.
	      The options will be printed in order that	the  passes  are  exe-
	      cuted.  If  more than one	listing	option is used,	the one	repre-
	      senting the earliest pass	takes effect.

	      Unrecognized options are ignored.

	      Both WarningList and ErrorList have the following	format:

	      [{FileName,[ErrorInfo]}].

	      ErrorInfo	is described below. The	file name  has	been  included
	      here  as	the  compiler uses the Erlang pre-processor epp, which
	      allows the code to be included in	other files. For this  reason,
	      it  is  important	to know	to which file an error or warning line
	      number refers.

       forms(Forms)

	      Is the same as  forms(File,  [verbose,report_errors,report_warn-
	      ings]).

       forms(Forms, Options) ->	CompRet

	      Types:

		 Forms = [Form]
		 CompRet = BinRet | ErrRet
		 BinRet	 = {ok,ModuleName,BinaryOrCode}	| {ok,ModuleName,Bina-
		 ryOrCode,Warnings}
		 BinaryOrCode =	binary() | term()
		 ErrRet	= error	| {error,Errors,Warnings}

	      Analogous	to file/1, but takes a list of forms  (in  the	Erlang
	      abstract	format	representation)	 as first argument. The	option
	      binary is	implicit; i.e.,	no object code file is	produced.  Op-
	      tions that would ordinarily produce a listing file, such as 'E',
	      will instead cause the internal format for  that	compiler  pass
	      (an Erlang term; usually not a binary) to	be returned instead of
	      a	binary.

       format_error(ErrorDescriptor) ->	chars()

	      Types:

		 ErrorDescriptor = errordesc()

	      Uses an ErrorDescriptor and returns a deep  list	of  characters
	      which  describes	the error. This	function is usually called im-
	      plicitly when an ErrorInfo structure is processed. See below.

       output_generated(Options) -> true | false

	      Types:

		 Options = [term()]

	      Determines whether the compiler would generate a beam file  with
	      the  given  options. true	means that a beam file would be	gener-
	      ated; false means	that the compiler would	generate some  listing
	      file,  return a binary, or merely	check the syntax of the	source
	      code.

       noenv_file(File,	Options) -> CompRet

	      Works exactly like file/2, except	that the environment  variable
	      ERL_COMPILER_OPTIONS is not consulted.

       noenv_forms(Forms, Options) -> CompRet

	      Works exactly like forms/2, except that the environment variable
	      ERL_COMPILER_OPTIONS is not consulted.

       noenv_output_generated(Options) -> true | false

	      Types:

		 Options = [term()]

	      Works exactly like output_generated/1, except that the  environ-
	      ment variable ERL_COMPILER_OPTIONS is not	consulted.

DEFAULT	COMPILER OPTIONS
       The  (host  operating system) environment variable ERL_COMPILER_OPTIONS
       can be used to give default compiler options. Its value must be a valid
       Erlang  term.  If  the value is a list, it will be used as is. If it is
       not a list, it will be put into a list.

       The list	will be	appended to any	options	given to file/2, forms/2,  and
       output_generated/2.   Use   the	 alternative  functions	 noenv_file/2,
       noenv_forms/2, or noenv_output_generated/2 if you don't want the	 envi-
       ronment	variable to be consulted (for instance,	if you are calling the
       compiler	recursively from inside	a parse	transform).

INLINING
       The compiler can	do function inlining within an Erlang module. Inlining
       means that a call to a function is replaced with	the function body with
       the arguments replaced with the actual values. The semantics  are  pre-
       served,	except if exceptions are generated in the inlined code.	Excep-
       tions will be reported as occurring in the function the	body  was  in-
       lined into. Also, function_clause exceptions will be converted to simi-
       lar case_clause exceptions.

       When a function is inlined, the original	function will be kept if it is
       exported	 (either by an explicit	export or if the export_all option was
       given) or if not	all calls to the function were inlined.

       Inlining	does not necessarily improve running time. For	instance,  in-
       lining may increase Beam	stack usage which will probably	be detrimental
       to performance for recursive functions.

       Inlining	is never default; it must be explicitly	enabled	 with  a  com-
       piler option or a -compile() attribute in the source module.

       To  enable  inlining,  either use the inline option to let the compiler
       decide which functions to inline	or {inline,[{Name,Arity},...]} to have
       the  compiler inline all	calls to the given functions. If the option is
       given inside a compile directive	in an Erlang module, {Name,Arity}  may
       be written as Name/Arity.

       Example of explicit inlining:

       -compile({inline,[pi/0]}).

       pi() -> 3.1416.

       Example of implicit inlining:

       -compile(inline).

       The {inline_size,Size} option controls how large	functions that are al-
       lowed to	be inlined. Default is 24, which will keep the size of the in-
       lined  code roughly the same as the un-inlined version (only relatively
       small functions will be inlined).

       Example:

       %% Aggressive inlining -	will increase code size.
       -compile(inline).
       -compile({inline_size,100}).

INLINING OF LIST FUNCTIONS
       The compiler can	also inline a variety of list  manipulation  functions
       from the	stdlib's lists module.

       This  feature  must  be	explicitly enabled with	a compiler option or a
       -compile() attribute in the source module.

       To enable inlining of list functions, use the inline_list_funcs option.

       The following functions are inlined:

	 * lists:all/2

	 * lists:any/2

	 * lists:foreach/2

	 * lists:map/2

	 * lists:flatmap/2

	 * lists:filter/2

	 * lists:foldl/3

	 * lists:foldr/3

	 * lists:mapfoldl/3

	 * lists:mapfoldr/3

PARSE TRANSFORMATIONS
       Parse transformations are used when a programmer	wants  to  use	Erlang
       syntax  but  with different semantics. The original Erlang code is then
       transformed into	other Erlang code.

ERROR INFORMATION
       The ErrorInfo mentioned above is	the standard ErrorInfo structure which
       is returned from	all IO modules.	It has the following format:

       {ErrorLine, Module, ErrorDescriptor}

       ErrorLine  will	be the atom none if the	error does not correspond to a
       specific	line (e.g. if the source file does not exist).

       A string	describing the error is	obtained with the following call:

       Module:format_error(ErrorDescriptor)

SEE ALSO
       epp(3), erl_id_trans(3),	erl_lint(3), beam_lib(3)

Ericsson AB			compiler 5.0.4			    compile(3)

NAME | DESCRIPTION | EXPORTS | DEFAULT COMPILER OPTIONS | INLINING | INLINING OF LIST FUNCTIONS | PARSE TRANSFORMATIONS | ERROR INFORMATION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=compile&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help