Remove The WriteEmitted Phase (#2390)

4 files changed, 8 insertions, 145 deletions

diff --git a/src/main/scala/firrtl/options/phases/WriteOutputAnnotations.scala b/src/main/scala/firrtl/options/phases/WriteOutputAnnotations.scala
index 2cf4c92f..ba38bb87 100644
--- a/src/main/scala/firrtl/options/phases/WriteOutputAnnotations.scala
+++ b/src/main/scala/firrtl/options/phases/WriteOutputAnnotations.scala
@@ -19,8 +19,14 @@ import java.io.{BufferedOutputStream, File, FileOutputStream, PrintWriter}
 
 import scala.collection.mutable
 
-/** [[firrtl.options.Phase Phase]] that writes an [[AnnotationSeq]] to a file. A file is written if and only if a
-  * [[StageOptions]] view has a non-empty [[StageOptions.annotationFileOut annotationFileOut]].
+/** [[firrtl.options.Phase Phase]] that writes an [[AnnotationSeq]] to the filesystem,
+  *  according to the following rules:
+  *  1) Annotations which extend [[CustomFileEmission]] are written seperately to their prescribed
+  *     destinations and replaced per [[[CustomFileEmission.replacements replacements]].
+  *  2) All remaining annotations are written to destination specified by
+  *    [[StageOptions.annotationFileOut annotationFileOut]], iff the stage option is set, with the following exceptions:
+  *    a) Annotations extending [[Unserializable]] are not written
+  *    b) Deleted annotations are not written unless [[StageOptions.writeDeleted writeDeleted]] is set
   */
 class WriteOutputAnnotations extends Phase {
 
diff --git a/src/main/scala/firrtl/stage/package.scala b/src/main/scala/firrtl/stage/package.scala
index a22d299a..92736963 100644
--- a/src/main/scala/firrtl/stage/package.scala
+++ b/src/main/scala/firrtl/stage/package.scala
@@ -4,7 +4,6 @@ package firrtl
 
 import firrtl.annotations.DeletedAnnotation
 import firrtl.options.OptionsView
-import firrtl.stage.phases.WriteEmitted
 import logger.LazyLogging
 
 /** The [[stage]] package provides an implementation of the FIRRTL compiler using the [[firrtl.options]] package. This
diff --git a/src/main/scala/firrtl/stage/phases/WriteEmitted.scala b/src/main/scala/firrtl/stage/phases/WriteEmitted.scala
deleted file mode 100644
index 647921d5..00000000
--- a/src/main/scala/firrtl/stage/phases/WriteEmitted.scala
+++ /dev/null
@@ -1,60 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-
-package firrtl.stage.phases
-
-import firrtl.{AnnotationSeq, EmittedCircuitAnnotation, EmittedModuleAnnotation, FileUtils}
-import firrtl.options.{Phase, StageOptions, Viewer}
-import firrtl.stage.FirrtlOptions
-
-import java.io.PrintWriter
-
-/** [[firrtl.options.Phase Phase]] that writes any [[EmittedAnnotation]]s in an input [[AnnotationSeq]] to one or more
-  * files. The input [[AnnotationSeq]] is viewed as both [[FirrtlOptions]] and [[firrtl.options.StageOptions
-  * StageOptions]] to determine the output filenames in the following way:
-  *   - [[EmittedModuleAnnotation]]s are written to a file in [[firrtl.options.StageOptions.targetDir
-  *     StageOptions.targetDir]] with the same name as the module and the [[EmittedComponent.outputSuffix outputSuffix]]
-  *     that the [[EmittedComponent]] specified
-  *   - [[EmittedCircuitAnnotation]]s are written to a file in [[firrtl.options.StageOptions.targetDir
-  *     StageOptions.targetDir]] using the [[FirrtlOptions.outputFileName]] viewed from the [[AnnotationSeq]]. If no
-  *     [[FirrtlOptions.outputFileName]] exists, then the top module/main name will be used. The
-  *     [[EmittedComponent.outputSuffix outputSuffix]] will be appended as needed.
-  *
-  * This does no sanity checking of the input [[AnnotationSeq]]. This simply writes any modules or circuits it sees to
-  * files. If you need additional checking, then you should stack an appropriate checking phase before this.
-  *
-  * Any annotations written to files will be deleted.
-  */
-@deprecated(
-  "Annotations that mixin the CustomFileEmission trait are automatically serialized by stages." +
-    "This will be removed in FIRRTL 1.5",
-  "FIRRTL 1.4.0"
-)
-class WriteEmitted extends Phase {
-
-  override def prerequisites = Seq.empty
-
-  override def optionalPrerequisiteOf = Seq.empty
-
-  override def invalidates(a: Phase) = false
-
-  /** Write any [[EmittedAnnotation]]s in an [[AnnotationSeq]] to files. Written [[EmittedAnnotation]]s are deleted. */
-  def transform(annotations: AnnotationSeq): AnnotationSeq = {
-    val fopts = Viewer[FirrtlOptions].view(annotations)
-    val sopts = Viewer[StageOptions].view(annotations)
-
-    annotations.flatMap {
-      case a: EmittedModuleAnnotation[_] =>
-        val target = FileUtils.getPath(sopts.getBuildFileName(a.value.name, Some(a.value.outputSuffix)))
-        os.write.over(target, a.value.value)
-        None
-      case a: EmittedCircuitAnnotation[_] =>
-        val target = FileUtils.getPath(
-          sopts.getBuildFileName(fopts.outputFileName.getOrElse(a.value.name), Some(a.value.outputSuffix))
-        )
-        os.write.over(target, a.value.value)
-        None
-      case a => Some(a)
-    }
-
-  }
-}
diff --git a/src/test/scala/firrtlTests/stage/phases/WriteEmittedSpec.scala b/src/test/scala/firrtlTests/stage/phases/WriteEmittedSpec.scala
deleted file mode 100644
index 8a2f8617..00000000
--- a/src/test/scala/firrtlTests/stage/phases/WriteEmittedSpec.scala
+++ /dev/null
@@ -1,82 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-
-package firrtlTests.stage.phases
-
-import java.io.File
-
-import firrtl._
-
-import firrtl.options.{Phase, TargetDirAnnotation}
-import firrtl.stage.OutputFileAnnotation
-import firrtl.stage.phases.WriteEmitted
-import org.scalatest.flatspec.AnyFlatSpec
-import org.scalatest.matchers.should.Matchers
-
-class WriteEmittedSpec extends AnyFlatSpec with Matchers {
-
-  def removeEmitted(a: AnnotationSeq): AnnotationSeq = a.flatMap {
-    case a: EmittedAnnotation[_] => None
-    case a => Some(a)
-  }
-
-  class Fixture { val phase: Phase = new WriteEmitted }
-
-  behavior.of(classOf[WriteEmitted].toString)
-
-  it should "write emitted circuits" in new Fixture {
-    val annotations = Seq(
-      TargetDirAnnotation("test_run_dir/WriteEmittedSpec"),
-      EmittedFirrtlCircuitAnnotation(EmittedFirrtlCircuit("foo", "", ".foocircuit")),
-      EmittedFirrtlCircuitAnnotation(EmittedFirrtlCircuit("bar", "", ".barcircuit")),
-      EmittedVerilogCircuitAnnotation(EmittedVerilogCircuit("baz", "", ".bazcircuit"))
-    )
-    val expected = Seq("foo.foocircuit", "bar.barcircuit", "baz.bazcircuit")
-      .map(a => new File(s"test_run_dir/WriteEmittedSpec/$a"))
-
-    info("annotations are unmodified")
-    phase.transform(annotations).toSeq should be(removeEmitted(annotations).toSeq)
-
-    expected.foreach { a =>
-      info(s"$a was written")
-      a should (exist)
-      a.delete()
-    }
-  }
-
-  it should "default to the output file name if one exists" in new Fixture {
-    val annotations = Seq(
-      TargetDirAnnotation("test_run_dir/WriteEmittedSpec"),
-      OutputFileAnnotation("quux"),
-      EmittedFirrtlCircuitAnnotation(EmittedFirrtlCircuit("qux", "", ".quxcircuit"))
-    )
-    val expected = new File("test_run_dir/WriteEmittedSpec/quux.quxcircuit")
-
-    info("annotations are unmodified")
-    phase.transform(annotations).toSeq should be(removeEmitted(annotations).toSeq)
-
-    info(s"$expected was written")
-    expected should (exist)
-    expected.delete()
-  }
-
-  it should "write emitted modules" in new Fixture {
-    val annotations = Seq(
-      TargetDirAnnotation("test_run_dir/WriteEmittedSpec"),
-      EmittedFirrtlModuleAnnotation(EmittedFirrtlModule("foo", "", ".foomodule")),
-      EmittedFirrtlModuleAnnotation(EmittedFirrtlModule("bar", "", ".barmodule")),
-      EmittedVerilogModuleAnnotation(EmittedVerilogModule("baz", "", ".bazmodule"))
-    )
-    val expected = Seq("foo.foomodule", "bar.barmodule", "baz.bazmodule")
-      .map(a => new File(s"test_run_dir/WriteEmittedSpec/$a"))
-
-    info("EmittedComponent annotations are deleted")
-    phase.transform(annotations).toSeq should be(removeEmitted(annotations).toSeq)
-
-    expected.foreach { a =>
-      info(s"$a was written")
-      a should (exist)
-      a.delete()
-    }
-  }
-
-}