Merge pull request #552 from MatthewFluet/llvm-codegen-docs

LLVM codegen documentation

bin/mlton-script

@@ -57,7 +57,7 @@ if [ -n "$GMP_LIB_DIR" ]; then
     gmpLinkOpts="-link-opt -L$GMP_LIB_DIR -target-link-opt netbsd -Wl,-R$GMP_LIB_DIR"
 fi
 
-# "Legacy" Pass Manager; LLVM < 13.0
+# "Legacy" Pass Manager; LLVM <= 14.0
 llvmOptOpt="-mem2reg -O2"
 # "New" Pass Manager; LLVM >= 13.0
 llvmOptOpt="--passes=function(mem2reg),default<O2>"

doc/guide/src/CompileTimeOptions.adoc

@@ -28,6 +28,12 @@ The default varies depending on architecture.
 Pass _option_ to `cc` when compiling assembler code.  If you wish to
 pass an option to the assembler, you must use `cc`’s `-Wa,` syntax.
 
+* ``-cc __cc__``
++
+Specify the executable for the C compiler.  The C compiler is also invoked to
+compile assembly (`.s` files) to object code (`.o` files) and to link object
+code into an executable.
+
 * ``-cc-opt __option__``
 +
 Pass _option_ to `cc` when compiling C code.
@@ -119,14 +125,29 @@ e.g. `-link-opt '-Lpath -lfoo'`.  If you wish to pass an option to the
 linker, you must use `cc`’s `-Wl,` syntax, e.g.,
 `-link-opt '-Wl,--export-dynamic'`.
 
+* ``-llvm-as __llvm-as__``
++
+Specify the executable for the LLVM `.ll` to `.bc` assembler;
+can be used to select a specific version of the tool (e.g., `-llvm-as llvm-as-14`).
+
 * ``-llvm-as-opt __option__``
 +
 Pass _option_ to `llvm-as` when assembling (`.ll` to `.bc`) LLVM code.
 
+* ``-llvm-llc __llc__``
++
+Specify the executable for the LLVM `.bc` to `.o` system compiler;
+can be used to select a specific version of the tool (e.g., `-llvm-as llc-14`).
+
 * ``-llvm-llc-opt __option__``
 +
 Pass _option_ to `llc` when compiling (`.bc` to `.o`) LLVM code.
 
+* ``-llvm-opt __opt__``
++
+Specify the executable for the LLVM `.bc` to `.bc` optimizer;
+can be used to select a specific version of the tool (e.g., `-llvm-opt opt-14`).
+
 * ``-llvm-opt-opt __option__``
 +
 Pass _option_ to `opt` when optimizing (`.bc` to `.bc`) LLVM code.

doc/guide/src/LLVMCodegen.adoc

@@ -5,15 +5,32 @@ The <<LLVMCodegen#>> is a <<Codegen#,code generator>> that translates the
 further optimized and compiled to native object code by the <<LLVM#>>
 toolchain.
 
-It requires <<LLVM#>> version 13.0 or greater to be installed.
-
 In benchmarks performed on the <<RunningOnAMD64#,AMD64>> architecture,
 code size with this generator is usually slightly smaller than either
 the <<AMD64Codegen#,native>> or the <<CCodegen#,C>> code generators. Compile
 time is worse than <<AMD64Codegen#,native>>, but slightly better than
 <<CCodegen#,C>>. Run time is often better than either <<AMD64Codegen#,native>>
 or <<CCodegen#,C>>.
 
+The <<LLVMCodegen#>> works by generating text LLVM IR (`.ll` files) and
+compiling it to object code (`.o` files) using the LLVM command-line tools:
+`llvm-as` (`.ll` to `.bc` assembler), `opt` (`.bc` to `.bc` optimizer), and
+`llc` (`.bc` to `.o` system compiler).  The `-llvm-as <llvm-as>`,
+`-llvm-opt <opt>`, and `-llvm-llc <llc>`
+<<CompileTimeOptions#,compile-time options>> can be used to specify the
+executables to be used when invoking the LLVM command-line tools, which can be
+used to select a specific version of the LLVM command-line tools (e.g.,
+`-llvm-as llvm-as-14 -llvm-opt opt-14 -llvm-llc llc-14`).
+
+<<Release20210117#,MLton 20210117>> requires LLVM 13 or 14, as it invokes `opt`
+using the
+https://releases.llvm.org/14.0.0/docs/ReleaseNotes.html#changes-to-the-llvm-ir:["legacy
+pass manager"].
+
+As of 20230522, MLton requires LLVM 14, as it invokes `opt` using the
+https://releases.llvm.org/14.0.0/docs/ReleaseNotes.html#changes-to-the-llvm-ir:["new
+pass manager"].
+
 == Implementation
 
 * https://github.com/MLton/mlton/blob/master/mlton/codegen/llvm-codegen/llvm-codegen.sig[`llvm-codegen.sig`]

man/mlton.1

@@ -49,6 +49,12 @@ Pass \fIoption\fP to \fBgcc\fP when compiling assembler code.  If you
 wish to pass an option to the assembler, you must use \fBgcc\fP's
 \fB\-Wa,\fP syntax.
 
+.TP
+\fB\-cc \fIcc\fP\fR
+Specify the executable for the C compiler.  The C compiler is also invoked to
+compile assembly (\fB.s\fP files) to object code (\fB.o\fP files) and to link
+object code into an executable.
+
 .TP
 \fB\-cc\-opt \fIoption\fP\fR
 Pass \fIoption\fP to \fBgcc\fP when compiling C code.
@@ -135,14 +141,29 @@ the same time, e.g. \fB\-link\-opt '\-Lpath \-lfoo'\fP.  If you wish to
 pass an option to the linker, you must use \fBgcc\fP's \fB\-Wl,\fP
 syntax, e.g., \fB\-link\-opt '\-Wl,\-\-export\-dynamic'\fP.
 
+.TP
+\fB\-llvm\-as \fIllvm\-as\fP\R
+Specify the executable for the LLVM \fB.ll\fP to \fB.bc\fP assembler;
+can be used to select a specific version of the tool (e.g., \fB\-llvm\-as llvm\-as\-14\fP).
+
 .TP
 \fB\-llvm\-as\-opt \fIoption\fP\fR
 Pass \fIoption\fP to \fBllvm-as\fP when assembling (\fB.ll\fP to \fB.bc\fP) LLVM code.
 
+.TP
+\fB\-llvm\-llc \fIllc\fP\R
+Specify the executable for the LLVM \fB.bc\fP to \fB.o\fP system compiler;
+can be used to select a specific version of the tool (e.g., \fB\-llvm\-llc llc\-14\fP).
+
 .TP
 \fB\-llvm\-llc\-opt \fIoption\fP\fR
 Pass \fIoption\fP to \fBllc\fP when compiling (\fB.bc\fP to \fB.o\fP) LLVM code.
 
+.TP
+\fB\-llvm\-opt \fIopt\fP\R
+Specify the executable for the LLVM \fB.bc\fP to \fB.bc\fP optimizer;
+can be used to select a specific version of the tool (e.g., \fB\-llvm\-opt opt\-14\fP).
+
 .TP
 \fB\-llvm\-opt\-opt \fIoption\fP\fR
 Pass \fIoption\fP to \fBopt\fP when optimizing (\fB.bc\fP to \fB.bc\fP) LLVM code.

mlton/main/main.fun

@@ -1,4 +1,4 @@
-(* Copyright (C) 2010-2011,2013-2022 Matthew Fluet.
+(* Copyright (C) 2010-2011,2013-2022,2024 Matthew Fluet.
  * Copyright (C) 1999-2009 Henry Cejtin, Matthew Fluet, Suresh
  *    Jagannathan, and Stephen Weeks.
  * Copyright (C) 1997-2000 NEC Research Institute.
@@ -265,7 +265,7 @@ fun makeOptions {usage} =
        (Expert, "bounce-rssa-usage-cutoff", "<n>",
         "Maximum variable use count to consider",
         Int (fn i => bounceRssaUsageCutoff := (if i < 0 then NONE else SOME i))),
-       (Expert, "cc", " <cc>", "set C compiler",
+       (Normal, "cc", " <cc>", "executable for C compiler",
         SpaceString
         (fn s => cc := String.tokens (s, Char.isSpace))),
        (Normal, "cc-opt", " <opt>", "pass option to C compiler",
@@ -584,7 +584,7 @@ fun makeOptions {usage} =
        (Expert, "link-opt-quote", " <opt>", "pass (quoted) option to linker",
         SpaceString
         (fn s => List.push (linkOpts, {opt = s, pred = OptPred.Yes}))),
-       (Expert, "llvm-as", " <llvm-as>", "path to llvm .ll -> .bc assembler",
+       (Normal, "llvm-as", " <llvm-as>", "executable for llvm .ll -> .bc assembler",
         SpaceString (fn s => llvm_as := s)),
        (Normal, "llvm-as-opt", " <opt>", "pass option to llvm assembler",
         (SpaceString o tokenizeOpt)
@@ -601,15 +601,15 @@ fun makeOptions {usage} =
                        | NONE => usage (concat ["invalid -llvm-aamd flag: ", s])))),
        (Expert, "llvm-cc10", " {false|true}", "use llvm 'cc10' for interchunk transfers",
         boolRef llvmCC10),
-       (Expert, "llvm-llc", " <llc>", "path to llvm .bc -> .o compiler",
+       (Normal, "llvm-llc", " <llc>", "executable for llvm .bc -> .o system compiler",
         SpaceString (fn s => llvm_llc := s)),
        (Normal, "llvm-llc-opt", " <opt>", "pass option to llvm compiler",
         (SpaceString o tokenizeOpt)
         (fn s => List.push (llvm_llcOpts, {opt = s, pred = OptPred.Yes}))),
        (Expert, "llvm-llc-opt-quote", " <opt>", "pass (quoted) option to llvm compiler",
         SpaceString
         (fn s => List.push (llvm_llcOpts, {opt = s, pred = OptPred.Yes}))),
-       (Expert, "llvm-opt", " <llvm-as>", "path to llvm .bc -> .bc optimizer",
+       (Normal, "llvm-opt", " <opt>", "executable for llvm .bc -> .bc optimizer",
         SpaceString (fn s => llvm_opt := s)),
        (Normal, "llvm-opt-opt", " <opt>", "pass option to llvm optimizer",
         (SpaceString o tokenizeOpt)