From 5041fb4b4c7e4bdba0d59d9f9eb62adcd8072542 Mon Sep 17 00:00:00 2001
From: Matthew Fluet <matthew.fluet@gmail.com>
Date: Thu, 14 Mar 2024 20:47:28 -0400
Subject: [PATCH] Document the `-llvm-{as,llc,opt}` compile-time options

---
 doc/guide/src/CompileTimeOptions.adoc | 15 +++++++++++++++
 man/mlton.1                           | 15 +++++++++++++++
 mlton/main/main.fun                   |  8 ++++----
 3 files changed, 34 insertions(+), 4 deletions(-)

diff --git a/doc/guide/src/CompileTimeOptions.adoc b/doc/guide/src/CompileTimeOptions.adoc
index 3955a7e590..f4078da7d6 100644
--- a/doc/guide/src/CompileTimeOptions.adoc
+++ b/doc/guide/src/CompileTimeOptions.adoc
@@ -119,14 +119,29 @@ e.g. `-link-opt '-Lpath -lfoo'`.  If you wish to pass an option to the
 linker, you must use `cc`&rsquo;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.
diff --git a/man/mlton.1 b/man/mlton.1
index 8f34479aa1..683af29870 100644
--- a/man/mlton.1
+++ b/man/mlton.1
@@ -135,14 +135,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.
diff --git a/mlton/main/main.fun b/mlton/main/main.fun
index 034554e933..d3bcc73f6e 100644
--- a/mlton/main/main.fun
+++ b/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.
@@ -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,7 +601,7 @@ 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)
@@ -609,7 +609,7 @@ fun makeOptions {usage} =
        (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)