FreeBSD Manual Pages
mlkit(1) MLKit - a compiler for Standard ML mlkit(1) NAME mlkit - A fullblown Standard ML compiler SYNOPSIS mlkit [OPTION]... [file.sml | file.sig | file.mlb] All possible options are listed below. DEFAULTS --SML_LIB You_did_not_set_path_to_install_dir, -aopt on, --alloc_pro- tect_always off, -argo off, -as as --64, -verbose off, --com- ments_in_asmcode off, -c off, -timings off, --contract on, -cr off, -cross_opt on, -dangle off, --dangling_pointers_statistics off, -debug off, -dcs off, --debug_linking off, --debug_man_enrich off, -Dpar off, --debug_which_at off, --delete_target_files on, --disable_atbot_analy- sis off, --disable_flow_var off, --disable_spurious_type_variables off, --eliminate_explicit_records on, --extra_gc_checks off, --fix_floating on, -gc on, -g off, -gengc off, --high_pointer_tagging on, -basislib on, --inline_functors off, --libs m,c,dl, -ldexe gcc14, -ldshared gcc14, -ltdce on, --log_to_file off, --maximum_inline_size 200, --maxi- mum_specialise_size 200, --messages on, --minimize_fixs on, --namebase dummyBase, --objs off, -opt on, -o run, -j 1, -par off, -par0 off, -ptc on, --pretty_depth 5, --pretty_string_size 80, --print_K_normal_forms off, -Ppp off, --print_bit_vectors off, --print_calc_offset_program off, -Pcee off, -Pccp off, -Pceb off, --print_constraints off, -Pdre off, -Pdresm off, -Peffects off, --print_excon_name off, -Peb off, --print_fetch_and_flush_program off, --print_linearised_program off, --print_lvar_name off, --print_normalized_program off, -Pole off, -Ppse off, -Ppeast off, -Prfg off, -Prip off, -Prsp off, -Prse0 off, -Pre- gions on, --print_register_allocated_program off, --print_rho_levels off, -Prho_protection off, --print_rho_types off, --print_simpli- fied_program off, -Psme off, -Ptypestamps off, -Ptypes off, -quot off, --raggedRight on, -scratch off, -ri on, -prof off, --regionvar ~1, --register_allocation on, --reml off, --report_boxities off, -sig off, -rep on, --safeLinkTimeElimination off, --specialize_recursive_func- tions on, --statistics_after_optimisation off, -stats_spurious off, --strip off, --tag_pairs off, -tag on, --type_check_lambda on, --un- box_function_arguments on, --unbox_reals on, -uncurry on, --val- ues_64bit on, --warn_on_escaping_puts off, --warn_on_parallel_puts off, --warn_spurious off, -w 100. DESCRIPTION When invoked, mlkit will compile the specified sources into an exe- cutable file run through a series of translation phases. The various options can be used to control the printing of intermediate forms and to control which optimizations are performed. If source files are or- ganised in ML Basis Files (files with extension .mlb), the compiler will memoize symbol table information and object code in the dedicated MLB directories located relative to the source files. If mlkit is invoked without source files, an interactive REPL is started. Type ':help;' within the REPL to learn more about its use. To learn more about programming with MLKit, consult the MLKit web page at http://melsman.github.io/mlkit STANDARDS The MLKit implements Standard ML (Revised 1997) and has almost full support for the Standard ML Basis Library (version of 2002). See the MLKit home page for a detailed overview of the support for the Standard ML Basis Library. EXAMPLES For examples, consult the MLKit manual "Programming with Regions in the MLKit", which is available from the MLKit home page. OPTIONS --SML_LIB S Installation directory for the MLKit standard library. For normal execution you should not modify this value. However, if you wish to use the MLKit with an altered runtime system you can update this setting and the system will try to link to a runtime system found in the specified install directory. --aggresive_opt, -aopt Enable aggressive optimisations, including constant folding and ag- gressive inlining. These optimisations are not guaranteed to be re- gion safe. Turning off garbage collection automatically turns off this option. --alloc_protect_always Always protect allocation when parallelism is enabled. That is, disregard the result of protection inference. --argobots, -argo When enabled, executables link with the Argobots lightweight thread library. --assembler S, -as S This option specifies the assembler used. On Linux the default is 'as --64'. On macOS, the default is 'as -q'. --chat, -verbose Print a message for each compilation step in the compiler. --comments_in_asmcode Insert comments in assembler code. --compile_only, -c Compile only. Suppresses generation of executable --compiler_timings, -timings Show compiler timings for each compilation phase. --contract Contract is responsible for inlining, specialization, elimination of dead code, and much else (Lambda Expression Optimiser). --contract_regions, -cr When this option is enabled, identically typed regions bound by the same letregion construct are unified. Moreover, region parameters to non-exported functions are trimmed whenever possible. --cross_module_opt, -cross_opt Enable cross-module optimisation including inlining of small func- tions and specialisation of small recursive functions. Which opti- misations are performed across modules is controlled by individual optimisation flags. --dangling_pointers, -dangle When this option is disabled, dangling pointers are avoided by forcing values captured in closures to live at-least as long as the closure itself. So as to make garbage collection sound, this option is disabled by default when garbage collection is enabled. --dangling_pointers_statistics When enabled, the compiler prints statistics about the number of times strengthening of the region typing rules (to avoid dangling pointers during evaluation) effects the target program. This flag is useful only when the flag -gc or -no_dangle is enabled. --debug_compiler, -debug Print intermediate forms of a program during compilation. --debug_constraint_solving, -dcs Debug ReML constraint solving. --debug_linking Debug linking of target code by showing which object files are linked together. --debug_man_enrich Show information about why a program unit need be recompiled. A program unit (or a functor body) is recompiled if either (a) the program unit is modified, or (b) information about an identifier for which the program unit depends upon has changed. --debug_parallelism, -Dpar Debug parallelism, including protection inference. --debug_which_at Debug storage mode analysis. --delete_target_files Delete assembler files produced by the compiler. If you disable this flag, you can inspect the assembler code produced by the com- piler. --disable_atbot_analysis Disable storage mode analysis. That is, turn all allocation direc- tives into attop. --disable_flow_var Disable optimised compilation of control-flow code, such as condi- tional expressions. --disable_spurious_type_variables Disable inference of spurious type variables. This option may crash the reference tracing garbage collector as it may result in dan- gling pointers. This flag is relevant only when garbage collection is enabled. --eliminate_explicit_records Eliminate bindings of explicit records only used for selections. Transform let r = (e1,...,en) in ... #i r .. #j r ... into let x1=e1 in ... let xn=en in ... xi .. xj ... (Lambda Ex- pression Optimiser). --extra_gc_checks Insert check for GC even in functions that do not allocate. --fix_floating Float fix-bindings into immediate let-bindings when possible to help tail-calls not be captured in let- region bindings. --garbage_collection, -gc Enable garbage collection. When enabled, regions are garbage col- lected during execution of the program. When garbage collection is enabled, all values are tagged. Due to region inference, for most programs, the garbage collector is invoked less often than for sys- tems based only on garbage collection. When garbage collection is enabled, introduction of dangling pointers are avoided by forcing values captured in closures to live at-least as long as the clo- sure. Moreover, enabling garbage collection implicitly enables the preservation of tail calls (see the option ``pre- serve_tail_calls''.) --gdb_support, -g When enabled, the compiler passes the option --gstabs to `as' (The GNU Assembler) and preserves the generated assembler files (.s files). Passing the --gstabs option to `as' makes it possible to step through the generated program using gdb (The GNU Debugger). --generational_garbage_collection, -gengc Enable generational garbage collection. Same as option garbage col- lection except that two generations are used for each region. --help Print extended help information and exit. --help S Print help information about an option and exit. --high_pointer_tagging When enabled, the 16 most-significant bits in pointers may be used for tagging. --import_basislib, -basislib Import Basis Library automatically in your projects. If you wish to make use of the Standard ML Basis Library in your projects, this option should be turned on, unless you wish to import the Basis Li- brary manually in your projects. --inline_functors Inline functors during static interpretation instead of generating separate target code blocks for functor bodies and arguments. With the flag enabled, performance may increase with the cost of larger (re)compilation times. The flag may be controlled in mlb-files us- ing mlb- annotations. --inline_names S Names of functions that should always be inlined if possible, no matter the setting of the flag --maximum_inline_size. --libdirs S This option controls where ld looks for archives. The format is a comma-separated list of directories; see the -libs entry. The de- fault is the empty list; thus 'ld' will look for libraries in only the system specific default directores. The directories are passed to 'ld' using the -L option. --libs S For accessing a foreign function residing in an archive named lib- NAME.a from Standard ML code (using prim), you need to add 'NAME' to this comma-separated list. Notice that an object file (with ex- tension '.o') is an archive if it is renamed to have extension '.a'. You may need to use the -libdirs option for specifying direc- tories for which ld should look for library archives. The libraries are passed to 'ld' using the -l option. --link_code S Link-files to be linked together to form an executable. --link_exe S, -ldexe S This option specifies the command used for linking an executable. The standard is to use 'gcc' for linking. When linking with c++ li- braries, 'g++' is the linker you want. On Linux the default is 'gcc14', whereas on newer macOS systems (Darwin > 23.1), the de- fault is 'gcc14 -Wl,-ld_classic,-stack_size,0x10000000' and on older macOS systems, the default is --link_shared S, -ldshared S This option specifies the command used for linking a shared object file. The standard is to use 'gcc' for linking. --link_time_dead_code_elimination, -ltdce Link time dead code elimination. --load_basis_files S, -load S Basis files to be loaded before compilation proper. --log_to_file Log to files instead of stdout. --man Print man-page and exit. --maximum_inline_size N Functions smaller than this size (counted in abstract syntax tree nodes) are inlined, even if they are used more than once. Functions that are used only once are always inlined. --maximum_specialise_size N Curried functions smaller than this size (counted in abstract syn- tax tree nodes) are specialised if all applications of the function within its own body are applied to its formal argument, even if they are used more than once. Functions that are used only once are specialised no matter their size. See also the option --special- ize_recursive_functions. --messages Print messages about reading source files and generating target files. --minimize_fixs Minimize fix constructs (Lambda Expression Optimiser). --mlb-subdir S For ensuring that the smart recompilation scheme is not reusing target-code compiled with different settings, a string provided with the mlb-subdir option can ensure the use of consistently gen- erated code. This option is Useful, in particular, when performing benchmarking. --mlb_path_maps S, -mlb-path-map S ML Basis path map files to be used. --namebase S Name base to enforce unique names when compiling mlb-files. --no_aggresive_opt, -no_aopt Opposite of --aggresive_opt, -aopt. --no_contract Opposite of --contract. --no_cross_module_opt, -no_cross_opt Opposite of --cross_module_opt, -cross_opt. --no_dangling_pointers, -no_dangle Opposite of --dangling_pointers, -dangle. --no_delete_target_files Opposite of --delete_target_files. --no_eliminate_explicit_records Opposite of --eliminate_explicit_records. --no_fix_floating Opposite of --fix_floating. --no_garbage_collection, -no_gc Opposite of --garbage_collection, -gc. --no_generational_garbage_collection, -no_gengc Opposite of --generational_garbage_collection, -gengc. --no_high_pointer_tagging Opposite of --high_pointer_tagging. --no_import_basislib, -no_basislib Opposite of --import_basislib, -basislib. --no_link_time_dead_code_elimination, -no_ltdce Opposite of --link_time_dead_code_elimination, -ltdce. --no_messages Opposite of --messages. --no_minimize_fixs Opposite of --minimize_fixs. --no_optimiser, -no_opt Opposite of --optimiser, -opt. --no_preserve_tail_calls, -no_ptc Opposite of --preserve_tail_calls, -ptc. --no_print_regions, -no_Pregions Opposite of --print_regions, -Pregions. --no_raggedRight Opposite of --raggedRight. --no_region_inference, -no_ri Opposite of --region_inference, -ri. --no_register_allocation Opposite of --register_allocation. --no_repository, -no_rep Opposite of --repository, -rep. --no_specialize_recursive_functions Opposite of --specialize_recursive_functions. --no_type_check_lambda Opposite of --type_check_lambda. --no_unbox_function_arguments Opposite of --unbox_function_arguments. --no_unbox_reals Opposite of --unbox_reals. --no_uncurrying, -no_uncurry Opposite of --uncurrying, -uncurry. --objs If enabled, MLKit writes object-file paths to the file run or the file specified by -output. The path to the runtime system (archive file) is included. The option is best used together with the option -no_delete_target_files. --optimiser, -opt Enable optimisation of intermediate language code (Lambda Expres- sions). Which optimisations are performed is controlled by individ- ual flags. The optimisations include function inlining, function specialisation, fix-minimization, unboxing of function arguments, and elimination of unnecessary record constructions. --output S, -o S The name of the executable file generated by the Kit. --parallel_compilation N, -j N The maximum number of parallel processes used for compilation. --parallelism, -par When enabled, the runtime system supports parallel threads. --parallelism_alloc_unprotected, -par0 When enabled, allocation into a region is not guaranteed to be atomic. --preserve_tail_calls, -ptc Avoid the wrapping of letregion constructs around tail calls. Turn- ing on garbage collection automatically turns on this option. --pretty_depth N This flag controls the pretty-printing depth of values printed in the REPL. The value must be an integer larger than zero. --pretty_string_size N This flag controls the pretty-printing size of strings printed in the REPL. The value must be an integer larger than zero. --print_K_normal_forms Print Region Expressions in K-Normal Form. Applicable, only after storage mode analysis has been applied. --print_all_program_points, -Ppp Print all program points when printing physical size inference ex- pressions. --print_bit_vectors --print_calc_offset_program --print_call_explicit_expression, -Pcee Print Region Expression with call annotations. --print_clos_conv_program, -Pccp Print Region Expression after closure conversion. --print_closed_export_bases, -Pceb Controls printing of closed export bases. --print_constraints Print ReML effect constraints when printing region and effect vari- ables. --print_drop_regions_expression, -Pdre Print Region Expression after dropping word regions and region ar- guments with only get-effects. --print_drop_regions_expression_with_storage_modes, -Pdresm Print Region Expression after dropping word regions and region ar- guments with only get-effects. Also print atbot and attop annota- tions resulting from storage mode analysis. --print_effects, -Peffects Print effects in region types. --print_excon_name Print underlying unique name when printing excons. --print_export_bases, -Peb Controls printing of export bases. --print_fetch_and_flush_program Print program with instructions for activation record fetching and flushing. --print_linearised_program Print a linearlised representation of the program unit. --print_lvar_name Print underlying unique name when printing lvars. --print_normalized_program Print Region Expression after K-normalisation. --print_opt_lambda_expression, -Pole Print Lambda Expression after optimisation. --print_physical_size_inference_expression, -Ppse Print Region Expression after physical size inference. --print_post_elab_ast, -Ppeast Print ast after elaboration. --print_region_flow_graph, -Prfg Print a region flow graph for the program fragment and generate a .vcg-file, which can be viewed using the xvcg program. --print_region_inferred_program, -Prip Print region-inferred program. --print_region_spreaded_program, -Prsp Print region-spreaded program. --print_region_static_env0, -Prse0 Print imported region static environment prior to region inference. --print_regions, -Pregions Print region variables in types and expressions. --print_register_allocated_program --print_rho_levels Print levels of region and effect variables in types and intermedi- ate forms. Levels control quantification of region and effect vari- ables. --print_rho_protection, -Prho_protection Print protectedness of region variables if set (P or U). --print_rho_types Print region types of region variables in types and intermediate forms. Possible region types are: p Type of regions containing pairs. a Type of regions containing arrays. r Type of regions containing references. t Type of regions containing triples. s Type of regions containing strings. T Type of regions containing other than the above kinds of values. --print_simplified_program Print simplified program after register allocation. --print_storage_mode_expression, -Psme Print Region Expression after storage mode analysis --print_type_name_stamps, -Ptypestamps Print type name stamps and their attributes in types and expres- sions. --print_types, -Ptypes Print types when printing intermediate forms. For Lambda Expres- sions, ordinary ML types are printed, whereas for Region Expres- sions, region types are printed. --quotation, -quot Enable support for quotations and anti-quotations. When enabled, the datatype datatype 'a frag = QUOTE of string | ANTIQUOTE 'a is available in the initial en- vironment. Moreover, values of this datatype may be constructed us- ing the quotation/antiquotation syntax: val s = "world" val a : string frag list = `hello ^s - goodbye` --raggedRight Use ragged right margin in pretty-printing of expressions and types. --recompile_basislib, -scratch Recompile basis library from scratch. This option is useful to- gether with other options that control code generation. --region_inference, -ri With this flag disabled, all values are allocated in global re- gions. --region_profiling, -prof Enable region profiling. Object code stemming from compiling a pro- gram with region profiling enabled is instrumented with profiling information. When a program compiled with region profiling enabled is run, the program produces a profile file run.rp, which can then be read by the profiling tool rp2ps that comes with the MLKit to produce profiling graphs of various forms. --regionvar N Uses the provided number as the id of the first generated region variable. When this option is provided together with the -c option, a file f.rv is written in the MLB/ directory with two numbers in it: the id for the first region variable generated and the id for the last region variable generated. The number given must be greater than any id for a top-level region/effect variable (>9). --register_allocation Perform register allocation. Without register allocation enabled, programs run somewhat slower--but they run and you save about 15 percent on compile time. --reml ReML is Standard ML with support for programming with explicit re- gions, explicit effects, and effect constraints. With ReML, atomic effects also include mutation effects. Whereas ReML include paral- lel thread support, ReML does not support integration with refer- ence-tracing garbage collection. --report_boxities Report for every datatype declaration the inferred boxity (repre- sentation) of its value constructors. --report_file_sig, -sig Report signatures for each file read. --repository, -rep Use in-memory repository to avoid unnecessary recompilation. This flag should be disabled when compiling mlb-files, which make use of the file system as a repository. --safeLinkTimeElimination Treat this module as a library in the sense that the code can be eliminated if it is not used, even if the code has side effects. --specialize_recursive_functions Specialise recursive functions. Use the option maximum_spe- cialise_size to control which functions are specialised. If this flag is on, functions that are applied only once are specialised, no matter the setting of maximum_specialise_size (Lambda Expression Optimiser). --statistics_after_optimisation Report optimisation statistics after optimisation of Lambda Expres- sion. --statistics_spurious, -stats_spurious Report statistics on spurious functions and instantiations of spu- rious type variable. This flag is relevant only when garbage col- lection is enabled. --strip If enabled, MLKit strips the generated executable. --tag_pairs Use a tagged representation of pairs for garbage collection. Garbage collection works fine with a tag-free representation of pairs, so this option is here for measurement purposes. --tag_values, -tag Enable tagging of values as used when garbage collection is enabled for implementing pointer traversal. --type_check_lambda Type check lambda expression prior to performing region inference. Type checking is very fast and for normal use you should not dis- able this option. Type checking intermediate forms is very powerful for eliminating bugs in the compiler. --unbox_function_arguments Unbox arguments to fix-bound functions, for which the argument `a' is used only in contexts `#i a'. All call sites are transformed to match the new function (Lambda Expression Optimiser). --unbox_reals Unbox real values and computations on real values inside functions. Real values stored in data structures and passed to functions are still boxed. --uncurrying, -uncurry Enable uncurrying of curried functions. The uncurried function takes its arguments unboxed in registers or on the stack. For par- tial applications and non- application uses of the function, appro- priate eta- expansions are applied. --values_64bit Support 64-bit values. Should be enabled for backends supporting 64-bit integers and words. --version, -v, -V Print version information and exit. --warn_on_escaping_puts Enable the compiler to issue a warning whenever a region type scheme contains a put effect on a region that is not quantified. --warn_on_parallel_puts Enable the compiler to issue a warning whenever a par-construct is passed functions with intersecting put effects. --warn_spurious Warn on the presence of a spurious type variable. This flag is rel- evant only when garbage collection is enabled. --width N, -w N Column width used when pretty printing intermediate code. EXIT STATUS Exits with status 0 on success and -1 on failure. ENVIRONMENT A library install directory must be provided in an environment variable SML_LIB or as a path-definition in either the system wide path-map /etc/mlkit/mlb-path-map or in the user's personal path-map ~/.mlkit/mlb-path-map. FILES /etc/mlkit/mlb-path-map System-wide configuration of library and runtime system loca- tions ~/.mlkit/mlb-path-map User specific configuration of library and runtime system loca- tions CREDITS The MLKit (version 2 and beyond) was developed by Lars Birkedal, Martin Elsman, Niels Hallenberg, Tommy H. Olesen, Mads Tofte, and Carsten Varming. People who have contributed with bug-fixes and improvements include Peter Bertelsen, Vesa Karvonen, Ken Friis Larsen, Henning Niss, Peter Sestoft, and Troels Henriksen. Nick Rothwell and David N. Turner took part in the development of the MLKit version 1. SEE ALSO See the MLKit manual "Programming with Regions in the MLKit", available from the MLKit home page http://melsman.github.io/mlkit for an in-depth introduction to programming with regions in the MLKit. The home page also provides an overview of which parts of the Standard ML Basis Library the MLKit implements, along with download and instal- lation instructions. version v4.7.13 2024-11-27 mlkit(1)
NAME | SYNOPSIS | DEFAULTS | DESCRIPTION | STANDARDS | EXAMPLES | OPTIONS | EXIT STATUS | ENVIRONMENT | FILES | CREDITS | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=mlkit&sektion=1&manpath=FreeBSD+Ports+15.0.quarterly>