reml(1)
💖 NAME 💖
reml — Standard ML with Explicit Regions and Effects, bestie ✨ (and yes, this is the reml(1) page straight out of MLKit, a compiler for Standard ML 🫶)
🌸 SYNOPSIS 🌸
reml [OPTION]... [file.sml | file.sig | file.mlb]Every single possible option is listed below. Like, all of them. We do not gatekeep here 💅
🎀 DEFAULTS 🎀
Okay so before you even touch a flag, here's exactly where everything sits out of the box. The whole lineup, no skipping 👑:
--SML_LIB→You_did_not_set_path_to_install_dir(iconic placeholder energy fr 💀)-aopt→off--alloc_protect_always→off-argo→off-as→as --64-verbose→off--comments_in_asmcode→off-c→off-timings→off-cfold→on--contract→on-cr→off-cross_opt→on-dangle→on--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_analysis→off--disable_flow_var→off-dufa→on--eliminate_explicit_records→on--fix_floating→on-g→off--high_pointer_tagging→on-basislib→on--inline_functors→off--libs→m,c,dl-ldexe→gcc-ldshared→gcc-ltdce→on--log_to_file→off-max_inl_sz→200-max_spec_sz→200--messages→on--minimize_fixs→on--namebase→dummyBase--objs→off-opt→on-o→run-j→1-par→on-par0→off-ptc→on--pretty_depth→5--pretty_string_size→80--print_K_normal_forms→off-Ppp→off-Paux→on--print_bit_vectors→off--print_calc_offset_program→off-Pcee→off-Pccp→off-Pceb→off--print_constraints→off-abbrev→on--print_control_prefix_infix→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-Pregions→on--print_register_allocated_program→off--print_rho_levels→off-Prho_protection→off--print_rho_types→off--print_simplified_program→off-Psme→off-Ptypestamps→off-Ptypes→off--raggedRight→on-scratch→off-ri→on-prof→off--register_allocation→on--reml→on--report_boxities→off-sig→off--safeLinkTimeElimination→off--specialize_recursive_functions→on-stats_opt→off--strip→off--type_check_lambda→on--unbox_funargs→on--unbox_real_funargs→on--unbox_reals→on-uncurry→on--warn_on_escaping_puts→off--warn_on_parallel_puts→off-w→100
🦋 DESCRIPTION 🦋
Okay so ReML is Standard ML with support for programming with explicit regions, explicit effects, and effect constraints. That's the whole vibe. With ReML, atomic effects include get-effects, put-effects, and mut-effects, and the parallel thread support is right there. What it does not do: ReML does not support integration with reference-tracing garbage collection. Noted, respected, moving on 💅
When you invoke reml, it will compile the specified sources into an executable file, run through a whole series of translation phases — think of it as the compiler's main-character arc 🌈. The various options let you control the printing of intermediate forms and control which optimizations get performed. So if you're nosy (affectionate), there's a flag for that.
If your source files are organised 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. Caching! We love a queen who remembers things 🎀
If reml is invoked without source files, an interactive REPL starts up instead. Type ':help;' within the REPL to learn more about how to use it — it's giving built-in bestie 🫶
To learn more about programming with ReML, consult the MLKit web page at
http://melsman.github.io/mlkit⭐ STANDARDS ⭐
ReML is based on the MLKit. The MLKit implements Standard ML (Revised 1997) and has almost full support for the Standard ML Basis Library (version of 2002) — like, almost full, bestie, don't come for me 😭. See the MLKit home page for a detailed overview of the support for the Standard ML Basis Library.
🔥 EXAMPLES 🔥
For examples, consult the files in the 'test/reml' folder within the github repository at http://github.com/melsman/mlkit. Real code, real receipts, go look 👑
✨ OPTIONS ✨
Here's the full menu. Every flag, every default, no cap 💖
--SML_LIB S— the installation directory for the MLKit standard library. For normal execution you should not modify this value, okay? But 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. Fancy 🦋--aggressive_opt,-aopt— enable aggressive optimisations, including aggressive inlining. Heads up though: these optimisations are not guaranteed to be region safe. Also, turning off garbage collection automatically turns off this option. It's giving "do it for the plot" 💀--alloc_protect_always— always protect allocation when parallelism is enabled. Like, disregard the result of protection inference entirely. Overprotective? Maybe. Safe? Yes 🛡️--argobots,-argo— when enabled, executables link with the Argobots lightweight thread library. Threads but make it lightweight 🌸--assembler S,-as S— specifies the assembler used. On Linux the default is'as --64'. On macOS, the default is'as -q'. Pick your fighter 💅--chat,-verbose— print a message for each compilation step in the compiler. It literally will not stop talking and honestly? Same 😭--comments_in_asmcode— insert comments in assembler code. Little notes for future you 🎀--compile_only,-c— compile only. Suppresses generation of executable.--compiler_timings,-timings— show compiler timings for each compilation phase. Time the tea ☕--constant_folding,-cfold— enable constant folding optimisations.--contract— Contract is responsible for inlining, specialization, elimination of dead code, and much else. It's the Lambda Expression Optimiser, and yes, it's the main character 👑--contract_regions,-cr— when this option is enabled, identically typed regions bound by the sameletregionconstruct are unified. Moreover, region parameters to non-exported functions are trimmed whenever possible. Tidy ✨--cross_module_opt,-cross_opt— enable cross-module optimisation, including inlining of small functions and specialisation of small recursive functions. Which optimisations are performed across modules is controlled by individual optimisation flags. Teamwork makes the dream work 🫶--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. And to make garbage collection sound, this option is disabled by default when garbage collection is enabled. Important safety moment ⚠️--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-gcor-no_dangleis enabled. Yes, that's exactly how it's worded. Numbers girlies rise 🙈--debug_compiler,-debug— print intermediate forms of a program during compilation. Peek behind the curtain 🎭--debug_constraint_solving,-dcs— debug ReML constraint solving.--debug_linking— debug linking of target code by showing which object files are linked together. It's giving receipts 🔍--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. Detective mode 🕵️--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 compiler. Your choice: clean workspace or hot gossip 🍓--disable_atbot_analysis— disable storage mode analysis. That is, turn all allocation directives intoattop.--disable_flow_var— disable optimised compilation of control-flow code, such as conditional expressions.--drop_unused_funargs,-dufa— drop function arguments that are unused. If nobody's using it, it's gone 💅--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 Expression Optimiser). Decluttered, slayed ✨
--fix_floating— float fix-bindings into immediate let-bindings when possible, to help tail-calls not be captured inlet-region bindings.--gdb_support,-g— when enabled, the compiler passes the option--gstabstoas(The GNU Assembler) and preserves the generated assembler files (.sfiles). Passing the--gstabsoption toasmakes it possible to step through the generated program using gdb (The GNU Debugger). Debug era 💀--help— print extended help information and exit.--help S— print help information about an option and exit. Yes, the argument comes after. Ask about one thing at a time bestie 🎀--high_pointer_tagging— when enabled, the 16 most-significant bits in pointers may be used for tagging. Smuggling data in the top bits, iconic 👑--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 Library manually in your projects. Then do you 💅--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, at the cost of larger (re)compilation times. The flag may be controlled in mlb-files using mlb-annotations. Trade-offs, always trade-offs 😭--inline_names S— names of functions that should always be inlined if possible, no matter the setting of the flag--maximum_inline_size. These ones get the VIP pass 🎟️--libdirs S— controls whereldlooks for archives. The format is a comma-separated list of directories; see the-libsentry. The default 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-Loption. (Yes, "directores". We keep it exactly as written 💖)--libs S— for accessing a foreign function residing in an archive namedlibNAME.afrom Standard ML code (usingprim), you need to add'NAME'to this comma-separated list. Notice that an object file (with extension'.o') is an archive if it is renamed to have extension'.a'. You may need to use the-libdirsoption for specifying directories for whichldshould look for library archives. The libraries are passed to'ld'using the-loption. Foreign function era 🌍--link_code S— link-files to be linked together to form an executable.--link_exe S,-ldexe S— specifies the command used for linking an executable. The standard is to use'gcc'for linking. When linking with c++ libraries,'g++'is the linker you want. On Linux the default is'gcc', whereas on macOS systems, the default is
(and that's genuinely where the sentence stops in the page — we love a cliffhanger 😭)
--link_shared S,-ldshared S— 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. Get your bases loaded first, always 🧚--log_to_file— log to files instead of stdout. Quiet mode, mysterious mode 🦋--man— print man-page and exit. You are here 📍--maximum_inline_size N,-max_inl_sz N— Bestie, any function smaller than this size (counted in abstract syntax tree nodes) gets inlined, even if it's used more than once. Functions used only once are always inlined. A function declared in one program unit may be inlined when applied in another program unit as long as it's sufficiently closed (refers only to exported identifiers) and the option--cross_optis enabled. ✨--maximum_specialise_size N,-max_spec_sz N— Function-parameterised functions smaller than this size (counted in abstract syntax tree nodes) are specialised if all applications of the function within its own body are applied to its formal function argument, even if they're used more than once. Functions used only once are specialised no matter their size. A function declared in one program unit may be specialised when applied in another program unit as long as it's sufficiently closed (refers only to exported identifiers) and the option--cross_optis enabled. Also see the option--specialize_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 themlb-subdiroption can ensure the use of consistently generated 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_aggressive_opt,-no_aopt— Opposite of--aggressive_opt,-aopt. 🙈--no_constant_folding,-no_cfold— Opposite of--constant_folding,-cfold. ✨--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_drop_unused_funargs,-no_dufa— Opposite of--drop_unused_funargs,-dufa. 💖--no_eliminate_explicit_records— Opposite of--eliminate_explicit_records. 🧚--no_fix_floating— Opposite of--fix_floating. 🍓--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_aux_reset,-no_Paux— Opposite of--print_aux_reset,-Paux. 🦋--no_print_control_abbrev_layout,-no_abbrev— Opposite of--print_control_abbrev_layout,-abbrev. 🎀--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_specialize_recursive_functions— Opposite of--specialize_recursive_functions. 🔥--no_type_check_lambda— Opposite of--type_check_lambda. 💖--no_unbox_funargs— Opposite of--unbox_funargs. 🍓--no_unbox_real_funargs— Opposite of--unbox_real_funargs. 🌸--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 filerunor 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 Expressions). Which optimisations are performed is controlled by individual 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 ofletregionconstructs around tail calls. Turning 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 expressions. 🦋--print_aux_reset,-Paux— Print resetting of auxiliary regions associated with construction of nullary constructor values. This flag affects the MulExp pretty printer. 💜--print_bit_vectors— No description on the page — just the flag itself, no invented lore 🙈.--print_calc_offset_program— No description on the page — just the flag itself, no invented lore 🙈.--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 variables. 🔥--print_control_abbrev_layout,-abbrev— Abbreviate layout of multiplicity expressions and call- explicit expressions. For instance, do not show at- annotations for top-level functions, do not show at- annotations for immediate constants, do not show region- bindings for zero-size regions that are associated only with immediate constants, do not show empty formal and actual region parameter lists, do not show'funcall', and do not show unique id for explicit region variables or explicit effect variables. 💅--print_control_prefix_infix— Prefix infix operations with module identifier to further indicate the type of the operation. 🎀--print_drop_regions_expression,-Pdre— Print Region Expression after dropping word regions and region arguments with only get-effects. 🦋--print_drop_regions_expression_with_storage_modes,-Pdresm— Print Region Expression after dropping word regions and region arguments with only get-effects. Also printatbotandattopannotations 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— Printastafter 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 thexvcgprogram. ⭐--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— No description on the page — just the flag itself, no invented lore 🙈.--print_rho_levels— Print levels of region and effect variables in types and intermediate forms. Levels control quantification of region and effect variables. 🎀--print_rho_protection,-Prho_protection— Print protectedness of region variables if set (PorU). 🔥--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 expressions. ⭐--print_types,-Ptypes— Print types when printing intermediate forms. For Lambda Expressions, ordinary ML types are printed, whereas for Region Expressions, region types are printed. 🌈--raggedRight— Use ragged right margin in pretty-printing of expressions and types. 🎀--recompile_basislib,-scratch— Recompile basis library from scratch. This option is useful together with other options that control code generation. 💜--region_inference,-ri— With this flag disabled, all values are allocated in global regions. 🧚--region_profiling,-prof— turns on region profiling ✨ Object code that comes from compiling a program with region profiling enabled gets instrumented with profiling information. Then, when you actually run a program compiled that way, it produces a profile file calledrun.rp, and you can feed that to the profiling toolrp2psthat ships with the MLKit to get profiling graphs in various forms. it's giving data visualization 💅--register_allocation— do register allocation. Turn this off and your programs run somewhat slower — but like, they still run, and you save about 15 percent on compile time 🎀--reml— ReML is Standard ML with support for programming with explicit regions, explicit effects, and effect constraints. With ReML, atomic effects also include mutation effects. And here's the fine print bestie: whereas ReML includes parallel thread support, currently, ReML does not support integration with reference-tracing garbage collection 🙈--report_boxities— report, for every datatype declaration, the inferred boxity (representation) of its value constructors. receipts for your datatypes 📋--report_file_sig,-sig— report signatures for each file read.--safeLinkTimeElimination— treat this module as a library in the sense that the code can be eliminated if it's not used, even if the code has side effects 👀 yes that's exactly what it says, no cap.--specialize_recursive_functions— specialise recursive functions. Use the optionmaximum_specialise_sizeto control which functions get specialised. And 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,-stats_opt— report optimisation statistics after optimisation of Lambda Expression. numbers!! we love numbers ⭐--strip— if enabled, MLKit strips the generated executable ✂️--type_check_lambda— type check lambda expression prior to performing region inference. Type checking is very fast, and for normal use you should not disable this option. Type checking intermediate forms is very powerful for eliminating bugs in the compiler — lowkey iconic 🧚--unbox_funargs— unbox arguments to fix-bound functions, for which the argument'a'is used only in contexts'#i a'. All call sites get transformed to match the new function (Lambda Expression Optimiser).--unbox_real_funargs— unbox arguments of typerealto fix-bound functions, for which the argument'a'is used only in contexts that unboxes'a'. All call sites are transformed to match the new function. Heads up: this optimisation has effect only when the flags'-unbox_funargs'and...
okay so the sentence literally trails off right there in the original manual 😭 "and" and then nothing. not me inventing the rest — I would never. mysteries of the manpage 🕵️♀️
--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 though, so don't get too excited 🍓--uncurrying,-uncurry— enable uncurrying of curried functions. The uncurried function takes its arguments unboxed in registers or on the stack. For partial applications and non-application uses of the function, appropriate eta-expansions are applied ✨--version,-v,-V— print version information and exit. that's it. that's the whole vibe check 👑--warn_on_escaping_puts— enables 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— enables the compiler to issue a warning whenever a par-construct is passed functions with intersecting put effects 🚨🚨--width N,-w N— column width used when pretty printing intermediate code. give it a number, bestie 💅
🦋 EXIT STATUS 🦋
Exits with status 0 on success and -1 on failure. that's the whole story — no dramatic third option, no plot twist 😌
🌈 ENVIRONMENT 🌈
A library install directory must be provided in an environment variable SML_LIB, as a path-definition in the user's personal path-map ~/.reml/mlb-path-map, or in a system wide path-map /nix/store/sfp5bfgah1f35wd1r96xrvhzx6nir1r6-mlkit-4.7.23/etc/reml/mlb-path-map.
Like, you gotta give it one of those three. it's not optional, fr fr 🫶
🎀 FILES 🎀
/nix/store/sfp5bfgah1f35wd1r96xrvhzx6nir1r6-mlkit-4.7.23/etc/reml/mlb-path-map— system-wide configuration of library and runtime system locations~/.reml/mlb-path-map— user specific configuration of library and runtime system locations
one for everyone, one just for you 💖
👑 CREDITS 👑
ReML was developed by Martin Elsman. Many people have helped developing the MLKit on which ReML is built; see the MLKit home page for details. shoutout to the whole team honestly 🙌
💜 SEE ALSO 💜
See the MLKit manual "Programming with Regions in the MLKit", available from the MLKit home page
http://melsman.github.io/mlkitfor 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 installation instructions.
go read it, it's giving required reading for the girlies who want to actually understand regions 📚✨
that's a wrap on reml(1)!! 🦋 this gorgeousness is version v4.7.23, and yes it's filed under reml(1) in that very section of the manual — mwah, love u, go compile something 💅🎀💖
📦 where this page comes from
- nixpkgs unstable: mlkit 4.7.23
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms