Merge branch 'master' into 3.4.x

.circleci/config.yml

@@ -139,6 +139,16 @@ jobs:
             - .m2
             - .sbt
 
+  test-chisel-docs:
+    executor: chisel-executor
+    steps:
+      - attach_workspace:
+          at: /home/chisel
+
+      - run:
+          command: |
+            sbt $SBT_ARGS "docs/mdoc"
+
   test-chisel-2_11:
     executor: chisel-executor
     steps:

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,18 +1,50 @@
-<!--
-Please select the item best describing the pull request in each category and delete the other items.
--->
-**Related issue**: <!-- if applicable -->
+### Contributor Checklist
+
+- [ ] Did you add Scaladoc to every public function/method?
+- [ ] Did you add at least one test demonstrating the PR?
+- [ ] Did you delete any extraneous printlns/debugging code?
+- [ ] Did you specify the type of improvement?
+- [ ] Did you add appropriate documentation in `docs/src`?
+- [ ] Did you state the API impact?
+- [ ] Did you specify the code generation impact?
+- [ ] Did you request a desired merge strategy?
+- [ ] Did you add text to be included in the Release Notes for this change?
+
+#### Type of Improvement
+
+<!-- Choose one or more from the following: -->
+<!--   - bug fix                            -->
+<!--   - performance improvement            -->
+<!--   - documentation                      -->
+<!--   - code refactoring                   -->
+<!--   - code cleanup                       -->
+<!--   - backend code generation            -->
+<!--   - new feature/API                    -->
 
-<!-- choose one -->
-**Type of change**: bug report | feature request | documentation | other enhancement
+#### API Impact
 
-<!-- choose one -->
-**Impact**: no functional change | API addition (no impact on existing code) | API modification
+<!-- How would this affect the current API? Does this add, extend, deprecate, remove, or break any existing API? -->
 
-<!-- choose one -->
-**Development Phase**: proposal |  implementation
+#### Backend Code Generation Impact
 
-**Release Notes**
+<!-- Does this change any generated Verilog?  -->
+<!-- How does it change it or in what circumstances would it?  -->
+
+#### Desired Merge Strategy
+
+<!-- If approved, how should this PR be merged? -->
+<!-- Options are: -->
+<!--   - Squash: The PR will be squashed and merged (choose this if you have no preference. -->
+<!--   - Rebase: You will rebase the PR onto master and it will be merged with a merge commit. -->
+
+#### Release Notes
 <!--
 Text from here to the end of the body will be considered for inclusion in the release notes for the version containing this pull request.
 -->
+
+### Reviewer Checklist (only modified by reviewer)
+- [ ] Did you add the appropriate labels?
+- [ ] Did you mark the proper milestone (3.2.x, 3.3.x, 3.4.0, 3.5.0) ?
+- [ ] Did you review?
+- [ ] Did you check whether all relevant Contributor checkboxes have been checked?
+- [ ] Did you mark as `Please Merge`?

.gitignore

@@ -6,8 +6,12 @@ generated/
 .idea_modules/
 .project
 target/
+docs-target/
 *.iml
 *.swp
+*.fir
+*.v
+*.json
 test_run_dir
 *~
 \#*\#

README.md

@@ -1,4 +1,4 @@
-![Chisel 3](https://raw.githubusercontent.com/freechipsproject/chisel3/master/doc/images/chisel_logo.svg?sanitize=true)
+![Chisel 3](https://raw.githubusercontent.com/freechipsproject/chisel3/master/docs/src/images/chisel_logo.svg?sanitize=true)
 
 ---
 
@@ -26,7 +26,7 @@ Chisel is powered by [FIRRTL (Flexible Intermediate Representation for RTL)](htt
 
 Consider an FIR filter that implements a convolution operation, as depicted in this block diagram:
 
-<img src="https://raw.githubusercontent.com/freechipsproject/chisel3/master/doc/images/fir_filter.svg?sanitize=true" width="512" />
+<img src="https://raw.githubusercontent.com/freechipsproject/chisel3/master/docs/src/images/fir_filter.svg?sanitize=true" width="512" />
 
 While Chisel provides similar base primitives as synthesizable Verilog, and *could* be used as such:
 
@@ -138,8 +138,8 @@ These are the base data types for defining circuit components:
 
 ![Image](https://raw.githubusercontent.com/freechipsproject/chisel3/master/doc/images/type_hierarchy.svg?sanitize=true)
 
-## Developer Documentation
-This section describes how to get started developing Chisel itself, including how to test your version locally against other projects that pull in Chisel using [sbt's managed dependencies](https://www.scala-sbt.org/1.x/docs/Library-Dependencies.html).
+## Contributor Documentation
+This section describes how to get started contributing to Chisel itself, including how to test your version locally against other projects that pull in Chisel using [sbt's managed dependencies](https://www.scala-sbt.org/1.x/docs/Library-Dependencies.html).
 
 ### Compiling and Testing Chisel
 
@@ -169,11 +169,11 @@ sbt test
 ### Running Projects Against Local Chisel
 
 To use the development version of Chisel (`master` branch), you will need to build from source and `publishLocal`.
-The repository version can be found in the build.sbt file.
+The repository version can be found in the [build.sbt](build.sbt) file.
 As of the time of writing it was:
 
 ```
-version := "3.2-SNAPSHOT"
+version := "3.4-SNAPSHOT"
 ```
 
 To publish your version of Chisel to the local Ivy (sbt's dependency manager) repository, run:
@@ -188,9 +188,32 @@ If you need to un-publish your local copy of Chisel, remove the directory genera
 In order to have your projects use this version of Chisel, you should update the `libraryDependencies` setting in your project's build.sbt file to:
 
 ```
-libraryDependencies += "edu.berkeley.cs" %% "chisel3" % "3.2-SNAPSHOT"
+libraryDependencies += "edu.berkeley.cs" %% "chisel3" % "3.4-SNAPSHOT"
+```
+
+### Building Chisel with FIRRTL in the same SBT Project
+
+While we recommend using the library dependency approach as described above, it is possible to build Chisel and FIRRTL in a single SBT project.
+
+**Caveats**
+* This only works for the "main" configuration; you cannot build the Chisel tests this way because `treadle` is only supported as a library dependency.
+* Do not `publishLocal` when building this way. The published artifact will be missing the FIRRTL dependency.
+
+This works by using [sbt-sriracha](http://eed3si9n.com/hot-source-dependencies-using-sbt-sriracha), an SBT plugin for toggling between source and library dependencies.
+It provides two JVM system properties that, when set, will tell SBT to include FIRRTL as a source project:
+* `sbt.sourcemode` - when set to true, SBT will look for FIRRTL in the workspace
+* `sbt.workspace` - sets the root directory of the workspace
+
+Example use:
+```bash
+# From root of this repo
+git clone git@github.com:freechipsproject/firrtl.git
+sbt -Dsbt.sourcemode=true -Dsbt.workspace=$PWD
 ```
 
+This is primarily useful for building projects that themselves want to include Chisel as a source dependency.
+As an example, see [Rocket Chip](https://github.com/chipsalliance/rocket-chip)
+
 ### Chisel3 Architecture Overview
 
 The Chisel3 compiler consists of these main parts:

build.sbt

@@ -28,8 +28,9 @@ def javacOptionsVersion(scalaVersion: String): Seq[String] = {
   }
 }
 
-val defaultVersions = Seq(
-  "edu.berkeley.cs" %% "firrtl" % "1.4-SNAPSHOT"
+val defaultVersions = Map(
+  "firrtl" -> "edu.berkeley.cs" %% "firrtl" % "1.4-SNAPSHOT",
+  "treadle" -> "edu.berkeley.cs" %% "treadle" % "1.3-SNAPSHOT"
 )
 
 lazy val commonSettings = Seq (
@@ -45,20 +46,6 @@ lazy val commonSettings = Seq (
   scalacOptions := Seq("-deprecation", "-feature") ++ scalacOptionsVersion(scalaVersion.value),
   libraryDependencies += "org.scala-lang" % "scala-reflect" % scalaVersion.value,
   addCompilerPlugin("org.scalamacros" % "paradise" % "2.1.1" cross CrossVersion.full),
-  // Use the root project's unmanaged base for all sub-projects.
-  unmanagedBase := (unmanagedBase in root).value,
-  // Since we want to examine the classpath to determine if a dependency on firrtl is required,
-  //  this has to be a Task setting.
-  //  Fortunately, allDependencies is a Task Setting, so we can modify that.
-  allDependencies := {
-    allDependencies.value ++ defaultVersions.collect {
-      // If we have an unmanaged jar file on the classpath, assume we're to use that,
-      case m: ModuleID if !(unmanagedClasspath in Compile).value.toString.contains(s"${m.name}.jar") =>
-        //  otherwise let sbt fetch the appropriate artifact, possibly with a specific revision.
-        val mWithRevision = m.withRevision(sys.props.getOrElse(m.name + "Version", m.revision))
-        mWithRevision
-    }
-  }
 )
 
 lazy val publishSettings = Seq (
@@ -109,7 +96,6 @@ lazy val chiselSettings = Seq (
     "junit" % "junit" % "4.13" % "test",
     "org.scalatest" %% "scalatest" % "3.1.2" % "test",
     "org.scalatestplus" %% "scalacheck-1-14" % "3.1.1.1" % "test",
-    "edu.berkeley.cs" %% "treadle" % "1.3-SNAPSHOT" % "test",
     "com.github.scopt" %% "scopt" % "3.7.1"
   ),
   javacOptions ++= javacOptionsVersion(scalaVersion.value)
@@ -179,7 +165,10 @@ lazy val macros = (project in file("macros")).
   settings(commonSettings: _*).
   settings(publishSettings: _*)
 
+lazy val firrtlRef = ProjectRef(workspaceDirectory / "firrtl", "firrtl")
+
 lazy val core = (project in file("core")).
+  sourceDependency(firrtlRef, defaultVersions("firrtl")).
   settings(commonSettings: _*).
   enablePlugins(BuildInfoPlugin).
   settings(
@@ -216,6 +205,7 @@ lazy val chisel = (project in file(".")).
   dependsOn(core).
   aggregate(macros, core, plugin).
   settings(
+    libraryDependencies += defaultVersions("treadle") % "test",
     scalacOptions in Test ++= Seq("-language:reflectiveCalls"),
     scalacOptions in Compile in doc ++= Seq(
       "-diagrams",
@@ -239,6 +229,22 @@ lazy val chisel = (project in file(".")).
     )
   )
 
+lazy val docs = project       // new documentation project
+  .in(file("docs-target")) // important: it must not be docs/
+  .dependsOn(chisel)
+  .enablePlugins(MdocPlugin)
+  .settings(usePluginSettings: _*)
+  .settings(commonSettings)
+  .settings(
+    scalacOptions += "-language:reflectiveCalls",
+    mdocIn := file("docs/src"),
+    mdocOut := file("docs/generated"),
+    mdocExtraArguments := Seq("--cwd", "docs"),
+    mdocVariables := Map(
+      "BUILD_DIR" -> "docs-target" // build dir for mdoc programs to dump temp files
+    )
+  )
+
 addCommandAlias("com", "all compile")
 addCommandAlias("lint", "; compile:scalafix --check ; test:scalafix --check")
 addCommandAlias("fix", "all compile:scalafix test:scalafix")