Improve --help ux for Canton sandbox (digital-asset#12990)

* Improve --help ux for Canton sandbox fixes digital-asset#12985 changelog_begin changelog_end * .
kgeonw · Feb 21, 2022 · 71fc352 · 71fc352
1 parent a9fd549
commit 71fc352
Show file tree

Hide file tree

Showing 4 changed files with 28 additions and 3 deletions.
diff --git a/daml-assistant/daml-helper/src/DA/Daml/Helper/Main.hs b/daml-assistant/daml-helper/src/DA/Daml/Helper/Main.hs
@@ -420,6 +420,23 @@ commandParser = subparser $ fold
         , help "Timeout of gRPC operations in seconds. Defaults to 60s. Must be > 0."
         ]
 
+    cantonHelpSwitch =
+      switch $
+      long "canton-help" <>
+      help "Display the help of the underlying Canton JAR instead of the Sandbox wrapper. This is only required for advanced options."
+
+    -- These options are common enough that we want them to show up in --help instead of only in
+    -- --canton-help.
+    cantonConfigOpts =
+      many $
+      option str $
+      long "config" <>
+      short 'c' <>
+      metavar "FILE" <>
+      help (unwords [ "Set configuration file(s)."
+                    , "If several configuration files assign values to the same key, the last value is taken."
+                    ])
+
     cantonSandboxCmd = do
         cantonOptions <- do
             cantonLedgerApi <- option auto (long "port" <> value 6865)
@@ -432,6 +449,8 @@ commandParser = subparser $ fold
                 (flag' True (long "static-time") <|>
                  flag' False (long "wall-clock-time") <|>
                  pure False)
+            cantonHelp <- cantonHelpSwitch
+            cantonConfigFiles <- cantonConfigOpts
             pure CantonOptions{..}
         portFileM <- optional $ option str (long "port-file" <> metavar "PATH"
             <> help "File to write ledger API port when ready")

diff --git a/daml-assistant/daml-helper/src/DA/Daml/Helper/Start.hs b/daml-assistant/daml-helper/src/DA/Daml/Helper/Start.hs
@@ -74,6 +74,8 @@ determineCantonOptions ledgerApiSpec SandboxCantonPortSpec{..} portFile = do
     cantonDomainAdminApi <- getPortForSandbox FreePort domainAdminApiSpec
     let cantonPortFileM = Just portFile -- TODO allow canton port file to be passed in from command line?
     let cantonStaticTime = StaticTime False
+    let cantonHelp = False
+    let cantonConfigFiles = []
     pure CantonOptions {..}
 
 withSandbox :: StartOptions -> FilePath -> [String] -> (Process () () () -> SandboxPort -> IO a) -> IO a

diff --git a/daml-assistant/daml-helper/src/DA/Daml/Helper/Util.hs b/daml-assistant/daml-helper/src/DA/Daml/Helper/Util.hs
@@ -259,7 +259,9 @@ withCantonSandbox options remainingArgs k = do
     let cantonJar = sdkPath </> "canton" </> "canton.jar"
     withTempFile $ \config -> do
         BSL.writeFile config (cantonConfig options)
-        withJar cantonJar [] ("daemon" : "-c" : config :  "--auto-connect-local" : remainingArgs) k
+        let args | cantonHelp options = ["--help"]
+                 | otherwise = concatMap (\f -> ["-c", f]) (cantonConfigFiles options)
+        withJar cantonJar [] ("daemon" : "-c" : config :  "--auto-connect-local" : (args <> remainingArgs)) k
 
 -- | Obtain a path to use as canton portfile, and give updated options.
 withCantonPortFile :: CantonOptions -> (CantonOptions -> FilePath -> IO a) -> IO a
@@ -281,6 +283,8 @@ data CantonOptions = CantonOptions
   , cantonDomainAdminApi :: Int
   , cantonPortFileM :: Maybe FilePath
   , cantonStaticTime :: StaticTime
+  , cantonHelp :: Bool
+  , cantonConfigFiles :: [FilePath]
   }
 
 cantonConfig :: CantonOptions -> BSL.ByteString

diff --git a/docs/source/tools/sandbox.rst b/docs/source/tools/sandbox.rst
@@ -188,8 +188,8 @@ To start Sandbox, run: ``daml sandbox [options] [-c canton.config]``.
 
 To see all the available options, run ``daml sandbox --help``. Note
 that this will show you the options of the Sandbox wrapper around
-Canton. To see options of the underlying Canton runner, use ``daml
-sandbox -- -- --help``.
+Canton. To see options of the underlying Canton runner, use
+``daml sandbox --canton-help``.
 
 Metrics
 *******