From ac56405a39f042c61042e80fc640ba390882ccb5 Mon Sep 17 00:00:00 2001 From: Jack Koenig Date: Tue, 16 Jan 2024 17:30:22 -0800 Subject: [PATCH] [website] Write new Installation doc --- docs/src/{appendix => }/appendix.md | 4 - docs/src/{cookbooks => }/cookbooks.md | 4 - docs/src/{developers => }/developers.md | 4 - docs/src/{explanations => }/explanations.md | 4 - docs/src/index.md | 14 +- docs/src/installation.md | 153 ++++++++++++++++++++ docs/src/{resources => }/resources.md | 6 - website/Makefile | 3 +- website/sidebars.js | 85 ++++++++++- website/src/pages/index.js | 4 +- 10 files changed, 248 insertions(+), 33 deletions(-) rename docs/src/{appendix => }/appendix.md (90%) rename docs/src/{cookbooks => }/cookbooks.md (94%) rename docs/src/{developers => }/developers.md (88%) rename docs/src/{explanations => }/explanations.md (98%) create mode 100644 docs/src/installation.md rename docs/src/{resources => }/resources.md (93%) diff --git a/docs/src/appendix/appendix.md b/docs/src/appendix.md similarity index 90% rename from docs/src/appendix/appendix.md rename to docs/src/appendix.md index 220b7b064d6..739003b74eb 100644 --- a/docs/src/appendix/appendix.md +++ b/docs/src/appendix.md @@ -1,7 +1,3 @@ ---- -sidebar_position: 3 ---- - # Appendix This section covers some less-common Chisel topics. diff --git a/docs/src/cookbooks/cookbooks.md b/docs/src/cookbooks.md similarity index 94% rename from docs/src/cookbooks/cookbooks.md rename to docs/src/cookbooks.md index ba755b27db5..4a21ecc52f3 100644 --- a/docs/src/cookbooks/cookbooks.md +++ b/docs/src/cookbooks.md @@ -1,7 +1,3 @@ ---- -sidebar_position: 1 ---- - # Cookbooks Welcome to the Chisel Cookbooks, where we capture frequently-used design patterns or troubleshooting questions. diff --git a/docs/src/developers/developers.md b/docs/src/developers.md similarity index 88% rename from docs/src/developers/developers.md rename to docs/src/developers.md index 900f3bec63c..85967c98dec 100644 --- a/docs/src/developers/developers.md +++ b/docs/src/developers.md @@ -1,7 +1,3 @@ ---- -sidebar_position: 4 ---- - # Developer Documentation Tips and tricks for Chisel developers: diff --git a/docs/src/explanations/explanations.md b/docs/src/explanations.md similarity index 98% rename from docs/src/explanations/explanations.md rename to docs/src/explanations.md index 528692ca20d..637e5bd1d7b 100644 --- a/docs/src/explanations/explanations.md +++ b/docs/src/explanations.md @@ -1,7 +1,3 @@ ---- -sidebar_position: 2 ---- - # Explanations Explanation documentation gives background and context. diff --git a/docs/src/index.md b/docs/src/index.md index 65d08c8798f..3138211b745 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -1,8 +1,4 @@ ---- -sidebar_position: 0 ---- - -# An Introduction to Chisel +# Introduction _Chisel_ (Constructing Hardware In a Scala Embedded Language) is a hardware @@ -17,8 +13,12 @@ reusable, you will find it important to leverage the underlying power of the Scala language. We recommend you consult one of the excellent Scala books to become more expert in Scala programming. -For a tutorial covering both Chisel and Scala, see the -[**online Chisel Bootcamp**](https://mybinder.org/v2/gh/freechipsproject/chisel-bootcamp/master). +:::tip + +Use **[Scala CLI](installation.md#quickstart-with-scala-cli)** to experiment with Chisel in seconds! + +::: + For quick reference "How-To" guides see the [Cookbooks](docs/cookbooks). diff --git a/docs/src/installation.md b/docs/src/installation.md new file mode 100644 index 00000000000..281acaa7eca --- /dev/null +++ b/docs/src/installation.md @@ -0,0 +1,153 @@ +--- +description: How to install and run Chisel +--- + +# Installation + +Chisel is a [Scala](https://www.scala-lang.org/) library and compiler plugin. + +## Quickstart with Scala CLI + +The easiest way to install Chisel is to [install Scala CLI](https://scala-cli.virtuslab.org/install) to build and run the Chisel template: + +```bash +wget https://github.com/chipsalliance/chisel/releases/latest/download/chisel-template.scala +scala-cli chisel-template.scala +``` + +The Chisel template is a simple, single-file example of Chisel that emits Verilog to the screen. + +:::tip + +While more complex projects often use a build tool like SBT or Mill as described below, +we still highly recommend using Scala CLI with the template for experimentation and +writing small snippets to share with others. + +::: + +## Dependencies + +As described above, Scala CLI is a great "batteries included" way to use Chisel. +It will automatically download and manage all dependencies of Chisel _including the JVM_. +More complex projects will require the user to install the JDK and a build tool. + +:::info + +Note that each of these dependencies are projects with their own installation instructions. +Please treat the commands below as suggestions and not directives. + +::: + +### Java Development Kit (JDK) + +Scala runs on the Java Virtual Machine (JVM), so it is necessary to install a JDK to use Chisel. +Chisel works on any version of Java newer than Java; however, we recommend using an LTS release version 17 or newer. +Note that Scala CLI requires Java 17 or newer so unless your system installation of Java is at least version 17, Scala CLI will download Java 17 for its own use. + +You can install any distribution of the JDK you prefer. +Eclipse Adoptium Temurin is a good option with support for all platforms: https://adoptium.net/installation + +#### Ubuntu + +```sh +apt install -y openjdk-17-jdk +``` + +#### MacOS + +Using [MacPorts](https://www.macports.org): +```sh +sudo port install openjdk17-temurin +``` + +Using [Homebrew](https://brew.sh): +```sh +brew tap homebrew/cask-versions +brew install --cask temurin17 +``` + +#### Windows + +Using [Scoop](https://scoop.sh): +```sh +scoop install temurin17-jdk +``` + +Windows users may also prefer using an [installer](https://adoptium.net/temurin/releases/?version=17&os=windows&arch=x86&package=jdk). + + +### Build Tools + +Scala CLI is only intended for projects made up of a single to a handful of files. +Larger projects need a build tool. + +#### Mill + +[Mill](https://mill-build.com) is a modern Scala build tool with simple syntax and a better command-line experience than SBT. +We recommend Chisel users use Mill. + +For detailed instructions, please see the [Mill documentation](https://mill-build.com/mill/Intro_to_Mill.html). + +##### Linux and MacOS + +The easiest way to use Mill is with the Mill Wrapper Script `millw`: + +```sh +curl -L https://raw.githubusercontent.com/lefou/millw/0.4.11/millw > mill && chmod +x mill +``` +You can then move this script to a global install location +```sh +sudo mv mill /usr/local/bin/ +``` + +##### Windows + +Using [Scoop](https://scoop.sh): +```sh +scoop install mill +``` + + +Download `millw.bat`: https://raw.githubusercontent.com/lefou/millw/0.4.11/millw.bat. + +#### SBT + +[SBT](https://www.scala-sbt.org) is the more traditional Scala build tool that has many resources and examples. +It is most productively used with its own REPL rather than on the command-line. + +##### Linux + +The easiest way to install SBT is manually from the release tarball. +Note that MacOS and Windows users can also do a manual install. + +```sh +curl -s -L https://github.com/sbt/sbt/releases/download/v1.9.8/sbt-1.9.8.tgz | tar xvz +``` + +Then copy the `sbt` bootstrap script into a global install location + +```sh +sudo mv sbt/bin/sbt /usr/local/bin/ +``` + +##### MacOS + +Using [MacPorts](https://www.macports.org): +```sh +sudo port install sbt +``` + +##### Windows + +Using [Scoop](https://scoop.sh): +```sh +scoop install sbt +``` + +### Firtool + +Beginning with version 6.0, Chisel will manage the version of firtool on most systems. +However, it may be necessary to build from source on some systems (eg. older Linux distributions). +If you need to build firtool from source, please see the [Github repository](https://github.com/llvm/circt). + +To see what version of firtool should be used for a given version of Chisel, see [Versioning](appendix/versioning#firtool-version). \ No newline at end of file diff --git a/docs/src/resources/resources.md b/docs/src/resources.md similarity index 93% rename from docs/src/resources/resources.md rename to docs/src/resources.md index 08f63c30c16..a5b154f6da5 100644 --- a/docs/src/resources/resources.md +++ b/docs/src/resources.md @@ -1,9 +1,3 @@ ---- -layout: docs -title: "Resources and References" -section: "chisel3" ---- - # Chisel Resources The *best resource* to learn about Chisel is the [**online Chisel Bootcamp**](https://mybinder.org/v2/gh/freechipsproject/chisel-bootcamp/master). This runs in your browser and assumes no prior Scala knowledge. (You may also run this locally via the [backing chisel-bootcamp GitHub repository](https://github.com/freechipsproject/chisel-bootcamp).) diff --git a/website/Makefile b/website/Makefile index ae25fbb4510..02e697f0c2f 100644 --- a/website/Makefile +++ b/website/Makefile @@ -54,7 +54,8 @@ $(latest_scaladoc_dir): $(latest_scaladoc_dir)/index.html: $(latest_version) | $(latest_scaladoc_dir) $(eval VER := $(shell cat $(latest_version))) $(eval URL := https://repo1.maven.org/maven2/org/chipsalliance/chisel_2.13/$(VER)/chisel_2.13-$(VER)-javadoc.jar) - cd $(latest_scaladoc_dir) && \ + rm -rf $(latest_scaladoc_dir)/* && \ + cd $(latest_scaladoc_dir) && \ wget -q -O temp.jar $(URL) && \ unzip -q temp.jar && \ rm -rf temp.jar diff --git a/website/sidebars.js b/website/sidebars.js index d89c3e95d38..dee18483cf5 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -3,7 +3,90 @@ /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ const sidebars = { - tutorialSidebar: [{type: 'autogenerated', dirName: '.'}], + chiselSidebar: [ + 'index', + { + type: 'category', + label: 'Getting Started', + link: { + type: 'generated-index', + }, + collapsed: false, + items: [ + 'installation', + ], + }, + { + type: 'category', + label: 'Cookbooks', + link: { + type: 'doc', + id: 'cookbooks', + }, + items: [ + { + type: 'autogenerated', + dirName: 'cookbooks', + }, + ] + }, + { + type: 'category', + label: 'Explanations', + link: { + type: 'doc', + id: 'explanations', + }, + items: [ + { + type: 'autogenerated', + dirName: 'explanations', + }, + ] + }, + { + type: 'category', + label: 'Appendix', + link: { + type: 'doc', + id: 'appendix', + }, + items: [ + { + type: 'autogenerated', + dirName: 'appendix', + }, + ] + }, + { + type: 'category', + label: 'Developer Documentation', + link: { + type: 'doc', + id: 'developers', + }, + items: [ + { + type: 'autogenerated', + dirName: 'developers', + }, + ] + }, + { + type: 'category', + label: 'Resources and References', + link: { + type: 'doc', + id: 'resources', + }, + items: [ + { + type: 'autogenerated', + dirName: 'resources', + }, + ] + }, + ] }; module.exports = sidebars; diff --git a/website/src/pages/index.js b/website/src/pages/index.js index 4b62a3f2324..c60cbb69927 100644 --- a/website/src/pages/index.js +++ b/website/src/pages/index.js @@ -17,8 +17,8 @@ function HomepageHeader() {
- Chisel Documentation + to="/docs/installation"> + Getting Started