smltojs(1)

📦
version 4.7.23 · 2 versions
, in nixpkgs unstable

💖 NAME 💖

okay bestie, welcome to smltojs(1) — the manual for smltojs, aka the Standard ML to JavaScript compiler. This is the SMLtoJs compiler's page, and we're gonna get you fluent, fr fr.

✨ SYNOPSIS ✨

smltojs [OPTION]... [file.sml | file.sig | file.mlb]

All possible options are listed below. Yes, all of them, bestie.

🎀 DEFAULTS 🎀

Factory settings, no cap — this is exactly what you get if you don't touch anything:

  • --SML_LIB You_did_not_set_path_to_install_dir
  • -aopt on
  • -verbose off
  • -c off
  • -timings off
  • -cfold on
  • --contract on
  • -cross_opt on
  • -debug off
  • --debug_linking off
  • --debug_man_enrich off
  • -dufa on
  • --eliminate_explicit_records on
  • -ebjs off
  • --fix_floating on
  • --high_pointer_tagging on
  • -basislib on
  • --inline_functors off
  • --js_dom_mode off
  • --js_path_compress off
  • -ltdce on
  • --log_to_file off
  • -max_inl_sz 200
  • -max_spec_sz 200
  • --messages on
  • --minimize_fixs on
  • --namebase dummyBase
  • -opt on
  • -o run
  • -j 1
  • --pretty_depth 5
  • --pretty_string_size 80
  • -Pceb off
  • --print_excon_name off
  • -Peb off
  • --print_lvar_name off
  • -Pole off
  • -Ppeast off
  • -Ptypestamps off
  • -Ptypes off
  • -quot off
  • --raggedRight on
  • -scratch off
  • --report_boxities off
  • -sig off
  • --safeLinkTimeElimination off
  • --specialize_recursive_functions on
  • -stats_opt off
  • --type_check_lambda on
  • --unbox_funargs on
  • -uncurry on
  • -w 100.

💅 DESCRIPTION 💅

When invoked, smltojs will compile the specified sources into an HTML-file, containing references to generated JavaScript files, 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 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.

To learn more about programming with SMLtoJs, consult the SMLtoJs web page at

http://www.smlserver.org/smltojs

🌈 STANDARDS 🌈

SMLtoJs 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).

🍓 EXAMPLES 🍓

For examples, consult the SMLtoJs home page. That's the whole vibe here, bestie.

👑 OPTIONS 👑

Here we go, one by one, with every flag and detail intact:

  • --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.
  • --aggressive_opt, -aopt — enable aggressive optimisations, including aggressive inlining. These optimisations are not guaranteed to be region safe. Turning off garbage collection automatically turns off this option.
  • --chat, -verbose — print a message for each compilation step in the compiler.
  • --compile_only, -c — compile only. Suppresses generation of executable.
  • --compiler_timings, -timings — show compiler timings for each compilation phase.
  • --constant_folding, -cfold — enable constant folding optimisations.
  • --contract — Contract is responsible for inlining, specialization, elimination of dead code, and much else (Lambda Expression Optimiser).
  • --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.
  • --debug_compiler, -debug — print intermediate forms of a program during compilation.
  • --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.
  • --drop_unused_funargs, -dufa — drop function arguments that are unused.
  • --eliminate_explicit_records — eliminate bindings of explicit records only used for selections. Transform this:
let r = (e1,...,en) in ... #i r .. #j r ...

into this:

let x1=e1 in ... let xn=en in ... xi .. xj ...

(Lambda Expression Optimiser).

  • --export_basis_js, -ebjs — when this flag is enabled, SmlToJs writes pickled bases to file.eb.js files to be read by js-client.
  • --fix_floating — float fix-bindings into immediate let-bindings when possible to help tail-calls not be captured in let- region bindings.
  • --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 Library 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 using 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.
  • --javascript_library_paths S, -jslibs S — use this option to add javascript library paths to the generated html and thereby allow for SML code to reference existing JavaScript libraries.
  • --js_dom_mode — generate a full HTML document including a proper HTML DOCTYPE specification.
  • --js_path_compress — compress (make canonical) Javascript file path references in the resulting run.html file.
  • --js_path_prefix S — prefix to add to each non-absolute Javascript file path in the resulting run.html file.
  • --js_path_relative_to S — absolute directory for which each absolute Javascript file path is made relative to in the resulting run.html file.
  • --link_code S — link-files to be linked together to form an executable.
  • --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, -max_inl_sz 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. A function declared in one program unit may be inlined when applied in another program unit provided the function is sufficiently closed (refers only to exported identifiers) and provided the option --cross_opt is 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 are used more than once. Functions that are 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 provided the function is sufficiently closed (refers only to exported identifiers) and provided the option --cross_opt is enabled. See also 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_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_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_raggedRight — opposite of --raggedRight.
  • --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_uncurrying, -no_uncurry — opposite of --uncurrying, -uncurry.
  • --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.
  • --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_closed_export_bases, -Pceb — controls printing of closed export bases.
  • --print_excon_name — print underlying unique name when printing excons.
  • --print_export_bases, -Peb — controls printing of export bases.
  • --print_lvar_name — print underlying unique name when printing lvars.
  • --print_opt_lambda_expression, -Pole — print Lambda Expression after optimisation.
  • --print_post_elab_ast, -Ppeast — print ast after elaboration.
  • --print_type_name_stamps, -Ptypestamps — prints type name stamps and their attributes in types and expressions. 💅
  • --print_types, -Ptypes — prints types when you’re printing intermediate forms. For Lambda Expressions, ordinary ML types get printed; for Region Expressions, region types get printed. ✨
  • --quotation, -quot — turns on support for quotations and anti-quotations. When it’s enabled, this datatype is available in the initial environment:
datatype 'a frag = QUOTE of string
                 | ANTIQUOTE 'a

Also, values of this datatype may be constructed using the quotation/antiquotation syntax:

val s = "world"
val a : string frag list = `hello ^s - goodbye`
  • --raggedRight — uses a ragged right margin when pretty-printing expressions and types. Very “let the right edge live its truth” of it. 🦋
  • --recompile_basislib, -scratch — recompiles the basis library from scratch. This option is useful together with other options that control code generation. 🔥
  • --report_boxities — reports the inferred boxity (representation) of every datatype declaration’s value constructors. So it’s giving “tell me the representation, bestie.” 🎀
  • --report_file_sig, -sig — reports signatures for each file read. 👑
  • --safeLinkTimeElimination — treats 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. Lowkey important: side effects do not save it from being eliminated here. 💀
  • --specialize_recursive_functions — specialises recursive functions. Use the option maximum_specialise_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, -stats_opt — reports optimisation statistics after optimisation of Lambda Expression. Numbers after the glow-up, basically. 📊
  • --type_check_lambda — type checks 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. 🫶
  • --unbox_funargs — unboxes 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). 🧚
  • --uncurrying, -uncurry — enables 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 — prints version information and exits. Slay, short and iconic. ⭐
  • --width N, -w N — column width used when pretty printing intermediate code. N is the width, bestie. 🎀

💀 EXIT STATUS 💀

Exits with status 0 on success and -1 on failure. That’s the whole vibe check. ✅❌

🌱 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 ~/.smltojs/mlb-path-map, or in a system wide path-map /nix/store/sfp5bfgah1f35wd1r96xrvhzx6nir1r6-mlkit-4.7.23/etc/smltojs/mlb-path-map.

bestie, it needs one of those three. Don’t leave it hanging. 🫶

📁 FILES 📁

  • /nix/store/sfp5bfgah1f35wd1r96xrvhzx6nir1r6-mlkit-4.7.23/etc/smltojs/mlb-path-map — system-wide configuration of library and runtime system locations 🏛️
  • ~/.smltojs/mlb-path-map — user specific configuration of library and runtime system locations 🏠

💖 CREDITS 💖

SMLtoJs was developed by Martin Elsman. Many people have helped developing the MLKit on which SMLtoJs is built; see the MLKit home page for details. 👑✨

👀 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 installation instructions. 🦋

Catch you later, bestie — this is the smltojs(1) page, version v4.7.23. The footer didn’t hand me a date, so I’m not inventing one; just regions, flags, and vibes 🫶💖

📦 where this page comes from