Add an -elab-only flag: stop compilation at the .ba

DEVELOP.md

@@ -163,6 +163,23 @@ flags are read from the `-c` invocation's command line (elaboration-affecting
 flags are baked into the `.ba`), and foreign-function `.ba` files are found
 via the same `-p`/`-bdir` search path as at link time.
 
+The mirror image is `-elab-only`, which makes a `-verilog` compile stop at
+the `.ba`, exactly as a Bluesim compile does: `genModuleVerilog` is not run
+at all, and every module's `.v` comes from `-c` or the link.  The flag is
+backend-agnostic when compiling source -- with `-sim` (or no backend)
+stopping at the `.ba` is already the behavior, so it is accepted as a
+no-op, letting build systems pass it unconditionally.  One knock-on
+effect: the port properties that `getIOProps` deduces (`const`, `reg`,
+`unused`, ...) are a codegen product fed back into the module's import-BVI
+wrapper, so under `-elab-only` they are absent -- as they always are for
+Bluesim -- and a parent that re-exports such a port loses the deduced
+annotation in its own `.v` header comment ("Ports:" blurb) and wrapper.
+Nothing structural consumes these deduced properties (the structural ones
+-- clock, reset, inout -- are attached by `AState`/`ASyntax` from
+`VModInfo`'s clock/reset fields, not from `getIOProps`), so per-module
+codegen from a given `.ba` is unchanged; only the annotation metadata in a
+parent's output can differ from a full compile's.
+
 ### Bluetcl
 
 * [Support for reflection in BSC](https://groups.io/g/b-lang-discuss/message/513)

doc/user_guide/user_guide.tex

@@ -827,6 +827,22 @@ \subsubsection{Generating code from elaborated files}
 example \te{-keep-fires}) take effect from the \te{-c} command line;
 elaboration choices are already recorded in the \te{.ba} file.
 
+\index{-elab-only@\te{-elab-only} (compiler flag)}
+Conversely, a Verilog compile can defer code generation entirely: with
+the \te{-elab-only} flag, \te{bsc -verilog -g mkFoo} stops after
+elaboration, writing only the \te{.ba} file for each module and no
+\te{.v}.  The Verilog is then produced from the \te{.ba} files by
+\te{-c} commands (for example, run in parallel by an external build
+system) or by the linking stage.  The generated modules are the same
+as a full compile's, except that port-property annotations deduced
+during a submodule's code generation (reported in the \te{.v}
+file-header comments) may be absent from modules whose submodules were
+compiled with \te{-elab-only}.  The flag applies when compiling source
+with any back end -- a Bluesim compile already stops after elaboration,
+so with \te{-sim} it is accepted as a no-op, and build systems can pass
+it unconditionally -- and cannot be combined with \te{-no-elab} (which
+would suppress the \te{.ba} files that later code generation needs).
+
 For Bluesim, the generated module is a reusable block: its C++ does
 not depend on where the module is later instantiated.  The top module
 of a Bluesim simulation is the one exception -- it is always generated
@@ -1597,6 +1613,7 @@ \subsection{Common compile and linking flags}
 \index{-e@\te{-e} (compiler flag)}
 \index{-o@\te{-o} (compiler flag)}
 \index{-elab@\te{-elab} (compiler flag)}
+\index{-elab-only@\te{-elab-only} (compiler flag)}
 \index{-c@\te{-c} (compiler flag)}
 \begin{centerboxverbatim}
 -g module             generate code for `module' (requires -sim or -verilog)
@@ -1609,6 +1626,8 @@ \subsection{Common compile and linking flags}
 -o name               name of generated executable
 -elab                 generate a .ba file after elaboration and scheduling
                       (on by default with -sim and -verilog)
+-elab-only            stop after elaboration: write .ba files but
+                      generate no code (-c or linking generates it later)
 \end{centerboxverbatim}
 
 

src/comp/Depend.hs

@@ -236,7 +236,11 @@ getGenFs flags pi =
             let mod_abin_files = map mkABinFileName (gens pi)
             in  foreign_abin_files ++ mod_abin_files
          Just Verilog ->
-            let mod_ver_files = map mkVerFileName (gens pi)
+            let -- with -elab-only, no .v is written, so a compile is up
+                -- to date without them (the .ba files are checked instead)
+                mod_ver_files = if (elabOnly flags)
+                                then []
+                                else map mkVerFileName (gens pi)
                 foreign_vpi_files = if (useDPI flags)
                                     then []
                                     else concatMap mkVPIFileNames (foreigns pi)

src/comp/Error.hs

@@ -1118,6 +1118,8 @@ data ErrMsg =
         | ETooManyBackends
         | EDollarNoVerilog
         | EDollarLink
+        | EElabOnlyNotSrcCompile
+        | EElabOnlyNoElab
         | EWrongBackend String String
         | ENoOptUndetNoXZ String
 
@@ -4263,6 +4265,17 @@ getErrorText EDollarLink =
     (System 57, empty,
      s2par ("The flag -remove-dollar in only supported for compiling source, not linking."))
 
+getErrorText EElabOnlyNotSrcCompile =
+    (System 100, empty,
+     s2par ("The flag -elab-only is only supported when compiling source, " ++
+            "not when linking or generating code with -c."))
+
+getErrorText EElabOnlyNoElab =
+    (System 101, empty,
+     s2par ("The flag -elab-only cannot be combined with -no-elab: " ++
+            "suppressing both the .v and the .ba files would leave no " ++
+            "generated output."))
+
 -- Removed System 58 ELicenseUnavailable, BSC is now open source
 -- Removed System 59 WLicenseExpires, BSC is now open source
 -- Removed System 60 WWaitForLicense, BSC is now open source

src/comp/Flags.hs

@@ -50,6 +50,7 @@ data Flags = Flags {
         dumps :: [(DumpFlag, Maybe FilePath)], -- dump to file or stdout
         enablePoisonPills :: Bool,
         codegenNames :: [String],
+        elabOnly :: Bool,
         entry :: Maybe String,
         expandATSlimit :: Int,
         expandIf :: Bool,

src/comp/FlagsDecode.hs

@@ -174,6 +174,13 @@ decodeArgs prog args cdir =
                            else -- We allow the file names to be omitted if the
                                 -- backend and entry point are both specified
                                 case (entry flags) of
+                                  -- -elab-only applies to compiling source,
+                                  -- not linking (checkLinkFlags rejects it
+                                  -- when file names are given)
+                                  (Just e) | (elabOnly flags)
+                                    -> (warnings,
+                                        DError [(cmdPosition,
+                                                 EElabOnlyNotSrcCompile)])
                                   (Just e) | (backend flags == Just Verilog)
                                     -> (warnings, DVerLink flags e [] [] [])
                                   (Just e) | (backend flags == Just Bluesim)
@@ -261,6 +268,14 @@ checkBSrcFlags flags filename =
         if (removeVerilogDollar flags && (backend flags /= Just Verilog))
         then DError [(cmdPosition, EDollarNoVerilog)]
         else
+        -- -elab-only stops compilation at the .ba; for Bluesim (or no
+        -- backend) stopping there is already the behavior, so the flag
+        -- is accepted with any backend.  Suppressing the .ba as well
+        -- would leave nothing generated.
+        if (elabOnly flags && (backend flags /= Nothing)
+                           && not (genABin flags))
+        then DError [(cmdPosition, EElabOnlyNoElab)]
+        else
         -- If the user hasn't allowed Bluesim/Verilog to diverge,
         -- then don't-cares can only be 2-state values
         if (not (optUndet flags) &&
@@ -296,6 +311,10 @@ checkLinkFlags flags names =
         if (removeVerilogDollar flags)
         then DError [(cmdPosition, EDollarLink)]
         else
+        -- -elab-only applies to compiling source, not linking
+        if (elabOnly flags)
+        then DError [(cmdPosition, EElabOnlyNotSrcCompile)]
+        else
         -- Verilog backend
         if (backend flags == Just Verilog)
         then -- An entry point must be specified
@@ -354,6 +373,10 @@ checkCodeGenFlags flags names =
             if (genSysC flags)
             then DError [(cmdPosition, EGenWithSystemC)]
             else
+            -- -elab-only suppresses exactly what -c generates
+            if (elabOnly flags)
+            then DError [(cmdPosition, EElabOnlyNotSrcCompile)]
+            else
             case (backend flags) of
               Nothing -> DError [(cmdPosition, ENoBackendCodeGen mods)]
               Just Bluesim ->
@@ -601,6 +624,7 @@ defaultFlags bluespecdir = Flags {
         doICheck = True,
         dumpAll = Nothing,
         dumps = [],
+        elabOnly = False,
         enablePoisonPills = False,
         entry = Nothing,
         expandATSlimit = 20,
@@ -1223,6 +1247,10 @@ externalFlags = [
          (Toggle (\f x -> f {genABin=x}) (showIfTrue genABin),
           "generate a .ba file after elaboration and scheduling (on by default with -sim, -verilog and -systemc; -no-elab suppresses)", Visible)),
 
+        ("elab-only",
+         (Toggle (\f x -> f {elabOnly=x}) (showIfTrue elabOnly),
+          "stop after elaboration: write .ba files but generate no code (-c or linking generates it later)", Visible)),
+
         ("expand-ATS-limit",
          (Arg "n"
           (\f s -> case (mread s) of
@@ -1909,6 +1937,7 @@ showFlagsRaw flags =
           ("doICheck", show (doICheck flags)),
           ("dumpAll", show (dumpAll flags)),
           ("dumps", show (dumps flags)),
+          ("elabOnly", show (elabOnly flags)),
           ("enablePoisonPills", show (enablePoisonPills flags)),
           ("entry", show (entry flags)),
           ("expandATSlimit", show (expandATSlimit flags)),

src/comp/GenABin.hs

@@ -34,7 +34,7 @@ import qualified Data.ByteString as B
 -- .ba file tag -- change this whenever the .ba format changes
 -- See also GenBin.header
 header :: [Byte]
-header = B.unpack $ TE.encodeUtf8 $ T.pack "bsc-ba-20260712-2"
+header = B.unpack $ TE.encodeUtf8 $ T.pack "bsc-ba-20260712-3"
 
 headerBS :: B.ByteString
 headerBS = B.pack header
@@ -568,10 +568,10 @@ instance Bin Flags where
                 a_100 a_101 a_102 a_103 a_104 a_105 a_106 a_107 a_108 a_109
                 a_110 a_111 a_112 a_113 a_114 a_115 a_116 a_117 a_118 a_119
                 a_120 a_121 a_122 a_123 a_124 a_125 a_126 a_127 a_128 a_129
-                a_130 a_131 a_132 a_133 a_134) =
-       do wr_chunk0; wr_chunk1; wr_chunk2; wr_chunk3; wr_chunk4; wr_chunk5; wr_chunk6; wr_chunk7; wr_chunk8
+                a_130 a_131 a_132 a_133 a_134 a_135) =
+       do wr_chunk0; wr_chunk1; wr_chunk2; wr_chunk3; wr_chunk4; wr_chunk5; wr_chunk6; wr_chunk7; wr_chunk8; wr_chunk9
       where
-        -- The 135-field serialization is split into NOINLINE chunks so
+        -- The 136-field serialization is split into NOINLINE chunks so
         -- that GHC optimizes bounded pieces: compiling it as a single
         -- monadic chain needs more than 15GB of heap.
         {-# NOINLINE wr_chunk0 #-}
@@ -619,6 +619,9 @@ instance Bin Flags where
           do toBin a_120; toBin a_121; toBin a_122; toBin a_123; toBin a_124;
              toBin a_125; toBin a_126; toBin a_127; toBin a_128; toBin a_129;
              toBin a_130; toBin a_131; toBin a_132; toBin a_133; toBin a_134
+        {-# NOINLINE wr_chunk9 #-}
+        wr_chunk9 =
+          do toBin a_135
     readBytes =
        do (a_000, a_001, a_002, a_003, a_004, a_005, a_006, a_007,
            a_008, a_009, a_010, a_011, a_012, a_013, a_014) <- rd_chunk0
@@ -638,6 +641,7 @@ instance Bin Flags where
            a_113, a_114, a_115, a_116, a_117, a_118, a_119) <- rd_chunk7
           (a_120, a_121, a_122, a_123, a_124, a_125, a_126, a_127,
            a_128, a_129, a_130, a_131, a_132, a_133, a_134) <- rd_chunk8
+          (a_135) <- rd_chunk9
           return (Flags
                 a_000 a_001 a_002 a_003 a_004 a_005 a_006 a_007 a_008 a_009
                 a_010 a_011 a_012 a_013 a_014 a_015 a_016 a_017 a_018 a_019
@@ -652,7 +656,7 @@ instance Bin Flags where
                 a_100 a_101 a_102 a_103 a_104 a_105 a_106 a_107 a_108 a_109
                 a_110 a_111 a_112 a_113 a_114 a_115 a_116 a_117 a_118 a_119
                 a_120 a_121 a_122 a_123 a_124 a_125 a_126 a_127 a_128 a_129
-                a_130 a_131 a_132 a_133 a_134)
+                a_130 a_131 a_132 a_133 a_134 a_135)
       where
         {-# NOINLINE rd_chunk0 #-}
         rd_chunk0 =
@@ -717,6 +721,10 @@ instance Bin Flags where
              a_130 <- fromBin; a_131 <- fromBin; a_132 <- fromBin; a_133 <- fromBin; a_134 <- fromBin
              return (a_120, a_121, a_122, a_123, a_124, a_125, a_126, a_127,
                      a_128, a_129, a_130, a_131, a_132, a_133, a_134)
+        {-# NOINLINE rd_chunk9 #-}
+        rd_chunk9 =
+          do a_135 <- fromBin
+             return (a_135)
 
 -- ----------
 

src/comp/bsc.hs

@@ -953,8 +953,12 @@ genModule
     --           IO properties which can be included as attributes in the
     --           Cmoduleverilog (import-BVI)
     --           XXX it would be nice if the Bluesim backend had the same info
+    -- With -elab-only, the Verilog backend stops at the .ba, like the
+    -- Bluesim backend: genModuleVerilog is not run at all, and a later
+    -- -c or link generates the .v from the .ba.  (The wrapper then has
+    -- no port properties, as with Bluesim.)
     (t, veriPortProps)
-        <- if (backend flags == Just Verilog)
+        <- if (backend flags == Just Verilog && not (elabOnly flags))
            then do (t', ips, _v)
                        <- genModuleVerilog
                              errh pps flags dumpnames t prefix modstr
@@ -1205,7 +1209,7 @@ genModuleVerilog errh pprops flags dumpnames time0 prefix moduleName
 
        -- Return
        -- * the port properties (to be included in the import-BVI)
-       -- * the Verilog structure (for accessing in bluetcl)
+       -- * the Verilog files written
        return (t, ips, vfilenames)
 
 

testsuite/bsc.options/bsc.help.out.expected

@@ -28,6 +28,7 @@ Compiler flags:
 -demote-errors list     treat a list of errors as warnings (``:'' sep list of tags)
 -e module               top-level module for simulation
 -elab                   generate a .ba file after elaboration and scheduling (on by default with -sim, -verilog and -systemc; -no-elab suppresses)
+-elab-only              stop after elaboration: write .ba files but generate no code (-c or linking generates it later)
 -fdir dir               working directory for relative file paths during elaboration
 -g module               generate code for ``module'' (requires -sim or -verilog)
 -help                   generate help message

testsuite/bsc.options/bsc.print-flags-raw.out.expected

@@ -21,6 +21,7 @@ Flags {
 	doICheck = True,
 	dumpAll = Nothing,
 	dumps = [],
+	elabOnly = False,
 	enablePoisonPills = False,
 	entry = Nothing,
 	expandATSlimit = 20,

testsuite/bsc.verilog/elab_only/ElabOnly.bsv

@@ -0,0 +1,22 @@
+// Fixtures for the -elab-only flag (a -verilog compile that writes
+// only .ba files, deferring the .v to -c or the linking stage)
+
+(* synthesize *)
+module mkESub(Reg#(Bit#(8)));
+   Reg#(Bit#(8)) rg <- mkReg(0);
+   return rg;
+endmodule
+
+(* synthesize *)
+module sysETb(Empty);
+   Reg#(Bit#(8)) sub <- mkESub;
+   Reg#(Bit#(4)) n <- mkReg(0);
+   rule bump;
+      sub <= sub + 2;
+      n <= n + 1;
+      if (n == 4) begin
+         $display("sub = %0d", sub);
+         $finish(0);
+      end
+   endrule
+endmodule

testsuite/bsc.verilog/elab_only/Makefile

@@ -0,0 +1,5 @@
+# for "make clean" to work everywhere
+
+CONFDIR = $(realpath ../..)
+
+include $(CONFDIR)/clean.mk