Merge branch 'master' into 3.5-release

Author: jackkoenig

.github/ISSUE_TEMPLATE.md

@@ -13,7 +13,7 @@ Please select the item best describing the issue in each category and delete the
 **Development Phase**: request | proposal
 
 **Other information**
- <!-- include detailed explanation, stacktraces, related issues, suggestions how to fix, links for us to have context, eg. Stack Overflow, gitter, etc -->
+ <!-- include detailed explanation, stacktraces, related issues, suggestions how to fix, links for us to have context, eg. Stack Overflow, gitter, Scastie (https://scastie.scala-lang.org/KtzZQ3nFTea9KoNh0tRqtg) -->
 
 **If the current behavior is a bug, please provide the steps to reproduce the problem:**
 

.github/workflows/test.yml

@@ -17,40 +17,17 @@ jobs:
         system: ["ubuntu-20.04"]
         jvm: ["adopt@1.8"]
         scala: ["2.13.6", "2.12.15"]
-        verilator: ["4.204"]
         espresso: ["2.4"]
     runs-on: ${{ matrix.system }}
 
     steps:
       - name: Checkout
         uses: actions/checkout@v2
 
-      - name: Install Z3
-        if: matrix.system == 'ubuntu-20.04'
-        run: |
-          sudo apt-get install -y z3
-          z3 --version
-
-      - name: Cache Verilator ${{ matrix.verilator }}
-        uses: actions/cache@v2.1.6
-        id: cache-verilator
+      - name: Install Tabby OSS Cad Suite (from YosysHQ)
+        uses: YosysHQ/setup-oss-cad-suite@v1
         with:
-          path: verilator-${{ matrix.verilator }}
-          key: ${{ matrix.system }}-verilator-${{ matrix.verilator }}
-      - name: Compile Verilator ${{ matrix.verilator }}
-        if: steps.cache-verilator.outputs.cache-hit != 'true'
-        run: |
-          wget https://github.com/verilator/verilator/archive/refs/tags/v${{ matrix.verilator }}.tar.gz
-          tar xvf v${{ matrix.verilator }}.tar.gz
-          cd verilator-${{ matrix.verilator }}
-          autoconf
-          ./configure
-          make
-      - name: Install Verilator ${{ matrix.verilator }}
-        run: |
-          cd verilator-${{ matrix.verilator }}
-          sudo make install
-          verilator --version
+          osscadsuite-version: '2021-11-09'
 
       - name: Install Espresso
         run: |
@@ -70,7 +47,7 @@ jobs:
         if: startsWith(matrix.scala, '2.12')
         run: sbt ++${{ matrix.scala }} docs/mdoc
       - name: Test
-        run: sbt ++${{ matrix.scala }} test noPluginTests/test
+        run: sbt ++${{ matrix.scala }} test
       - name: Binary compatibility
         run: sbt ++${{ matrix.scala }} mimaReportBinaryIssues
 
@@ -80,11 +57,10 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v2
-      - name: Install Verilator and Z3
-        run: |
-          sudo apt-get install -y verilator z3
-          verilator --version
-          z3 --version
+      - name: Install Tabby OSS Cad Suite (from YosysHQ)
+        uses: YosysHQ/setup-oss-cad-suite@v1
+        with:
+          osscadsuite-version: '2021-11-09'
       - name: Install Espresso
         run: |
           cd /tmp

CONTRIBUTING.md

@@ -0,0 +1,16 @@
+## GUIDE TO CONTRIBUTING
+
+1. If you need help on making a pull request, follow this [guide](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests).
+
+2. To understand how to compile and test chisel3 from the source code, follow the instructions in [SETUP.md](https://github.com/chipsalliance/chisel3/blob/master/SETUP.md).
+
+3. In order to contribute to chisel3, you'll need to sign the CLA agreement. You will be asked to sign it upon your first pull request.
+
+<!-- This ones helped me a lot -->
+
+4. To introduce yourself and get help, you can join the [gitter](https://gitter.im/freechipsproject/chisel3) forum. If you have any questions or concerns, you can get help there.
+
+5. You can peruse the [good-first-issues](https://github.com/chipsalliance/chisel3/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) for easy tasks to start with. Another easy thing to start with is doing your own pass of the [website](https://www.chisel-lang.org/chisel3/docs/introduction.html) looking for typos, pages missing their titles, etc. The sources for the website are [here](https://github.com/chipsalliance/chisel3/tree/master/docs).
+
+6. Please make your PRs against the `master` branch. The project admins, when reviewing your PR, will decide which stable version (if any) your change should be backported to. The backports will be opened automatically on your behalf and you may need to do some cleanup, but focus first on your `master` PR.
+

README.md

@@ -111,15 +111,24 @@ If you like a textbook to learn Chisel and also a bit of digital design in gener
 
 ### Build Your Own Chisel Projects
 
-See [the setup instructions](https://github.com/chipsalliance/chisel3/blob/master/SETUP.md) for how to set up your environment to run Chisel locally.
+See [the setup instructions](SETUP.md) for how to set up your environment to build Chisel locally.
 
-When you're ready to build your own circuits in Chisel, **we recommend starting from the [Chisel Template](https://github.com/freechipsproject/chisel-template) repository**, which provides a pre-configured project, example design, and testbench. Follow the [chisel-template readme](https://github.com/freechipsproject/chisel-template) to get started.
+When you're ready to build your own circuits in Chisel, **we recommend starting from the [Chisel Template](https://github.com/freechipsproject/chisel-template) repository**, which provides a pre-configured project, example design, and testbench.
+Follow the [chisel-template README](https://github.com/freechipsproject/chisel-template) to get started.
 
-If you insist on setting up your own project, the magic SBT lines are:
+If you insist on setting up your own project from scratch, your project needs to depend on both the chisel3-plugin (Scalac plugin) and the chisel3 library.
+For example, in SBT this could be expressed as:
 ```scala
-libraryDependencies += "edu.berkeley.cs" %% "chisel3" % "3.4.0"
-libraryDependencies += "edu.berkeley.cs" %% "chiseltest" % "0.3.0" % "test"
+// build.sbt
+scalaVersion := "2.12.13"
+addCompilerPlugin("edu.berkeley.cs" % "chisel3-plugin" % "3.4.4" cross CrossVersion.full)
+libraryDependencies += "edu.berkeley.cs" %% "chisel3" % "3.4.4"
+scalacOptions += "-Xsource:2.11"
+// We also recommend using chiseltest for writing unit tests 
+libraryDependencies += "edu.berkeley.cs" %% "chiseltest" % "0.3.4" % "test"
 ```
+### Guide For New Contributors
+If you are trying to make a contribution to this project, please read [CONTRIBUTING.md](https://github.com/Burnleydev1/chisel3/blob/recent_PR/CONTRIBUTING.md)
 
 ### Design Verification
 
@@ -136,6 +145,8 @@ These simulation-based verification tools are available for Chisel:
 - [**ScalaDoc**](https://www.chisel-lang.org/api/latest/chisel3/index.html), a listing, description, and examples of the functionality exposed by Chisel
 - [**Gitter**](https://gitter.im/freechipsproject/chisel3), where you can ask questions or discuss anything Chisel
 - [**Website**](https://www.chisel-lang.org) ([source](https://github.com/freechipsproject/www.chisel-lang.org/))
+- [**Scastie (3.5.0-RC1)**](https://scastie.scala-lang.org/KtzZQ3nFTea9KoNh0tRqtg)
+- [**asic-world**](http://www.asic-world.com/verilog/veritut.html) If you aren't familiar with verilog, this is a good tutorial.
 
 If you are migrating from Chisel2, see [the migration guide](https://www.chisel-lang.org/chisel3/chisel3-vs-chisel2.html).
 
@@ -155,18 +166,11 @@ The [Useful Resources](#useful-resources) for users are also helpful for contrib
 
 ### Compiling and Testing Chisel
 
-First, clone and build the master branch of [FIRRTL](https://github.com/chipsalliance/firrtl) and [Treadle](https://github.com/chipsalliance/treadle), as the master branch of Chisel may depend on unreleased changes in those projects:
-
-```
-git clone https://github.com/chipsalliance/firrtl.git
-git clone https://github.com/chipsalliance/treadle.git
-pushd firrtl; sbt publishLocal; popd
-pushd treadle; sbt publishLocal; popd
-```
+You must first install required dependencies to build Chisel locally, please see [the setup instructions](SETUP.md).
 
 Clone and build the Chisel library:
 
-```
+```bash
 git clone https://github.com/chipsalliance/chisel3.git
 cd chisel3
 sbt compile
@@ -185,14 +189,6 @@ If the compilation succeeded and the dependencies noted above are installed, you
 sbt test
 ```
 
-
-
-If you would like to run the tests without the compiler plugin (less common), you can do so by first launching `sbt`,
-then running `noPluginTests / test`:
-```
-sbt
-> noPluginTests / test
-```
 ### Running Projects Against Local Chisel
 
 To use the development version of Chisel (`master` branch), you will need to build from source and `publishLocal`.

build.sbt

@@ -16,7 +16,7 @@ lazy val commonSettings = Seq (
   organization := "edu.berkeley.cs",
   version := "3.5.0-RC2",
   autoAPIMappings := true,
-  scalaVersion := "2.13.6",
+  scalaVersion := "2.12.15",
   crossScalaVersions := Seq("2.13.6", "2.12.15"),
   scalacOptions := Seq("-deprecation", "-feature"),
   libraryDependencies += "org.scala-lang" % "scala-reflect" % scalaVersion.value,
@@ -71,9 +71,9 @@ lazy val chiselSettings = Seq (
   name := "chisel3",
 
   libraryDependencies ++= Seq(
-    "org.scalatest" %% "scalatest" % "3.2.9" % "test",
+    "org.scalatest" %% "scalatest" % "3.2.10" % "test",
     "org.scalatestplus" %% "scalacheck-1-14" % "3.2.2.0" % "test",
-    "com.lihaoyi" %% "os-lib" % "0.7.8",
+    "com.lihaoyi" %% "os-lib" % "0.8.0",
   ),
 ) ++ (
   // Tests from other projects may still run concurrently
@@ -113,7 +113,8 @@ lazy val pluginScalaVersions = Seq(
   "2.13.3",
   "2.13.4",
   "2.13.5",
-  "2.13.6"
+  "2.13.6",
+  "2.13.7"
 )
 
 lazy val plugin = (project in file("plugin")).
@@ -220,15 +221,6 @@ lazy val chisel = (project in file(".")).
     )
   )
 
-lazy val noPluginTests = (project in file ("no-plugin-tests")).
-  dependsOn(chisel).
-  settings(commonSettings: _*).
-  settings(chiselSettings: _*).
-  settings(Seq(
-    // Totally don't know why GitHub Action won't introduce FIRRTL to dependency.
-    libraryDependencies += defaultVersions("firrtl"),
-  ))
-
 // tests elaborating and executing/formally verifying a Chisel circuit with chiseltest
 lazy val integrationTests = (project in file ("integration-tests")).
   dependsOn(chisel).
@@ -246,7 +238,11 @@ lazy val docs = project       // new documentation project
   .settings(usePluginSettings: _*)
   .settings(commonSettings)
   .settings(
-    scalacOptions += "-language:reflectiveCalls",
+    scalacOptions ++= Seq(
+      "-Xfatal-warnings",
+      "-language:reflectiveCalls",
+      "-language:implicitConversions"
+    ),
     mdocIn := file("docs/src"),
     mdocOut := file("docs/generated"),
     // None of our links are hygienic because they're primarily used on the website with .html

build.sc

@@ -45,7 +45,7 @@ trait CommonModule extends CrossSbtModule with PublishModule {
   override def moduleDeps = super.moduleDeps ++ firrtlModule
 
   override def ivyDeps = super.ivyDeps() ++ Agg(
-    ivy"com.lihaoyi::os-lib:0.7.8",
+    ivy"com.lihaoyi::os-lib:0.8.0",
   ) ++  firrtlIvyDeps
 
   def publishVersion = "3.5.0-RC2"
@@ -107,7 +107,7 @@ class chisel3CrossModule(val crossScalaVersion: String) extends CommonModule wit
     override def scalacPluginClasspath = m.scalacPluginClasspath
 
     override def ivyDeps = m.ivyDeps() ++ Agg(
-      ivy"org.scalatest::scalatest:3.2.9",
+      ivy"org.scalatest::scalatest:3.2.10",
       ivy"org.scalatestplus::scalacheck-1-14:3.2.2.0",
     ) ++ m.treadleIvyDeps