[website] Write new Installation doc

docs/src/appendix/appendix.md → docs/src/appendix.md

@@ -1,7 +1,3 @@
----
-sidebar_position: 3
----
-
 # Appendix
 
 This section covers some less-common Chisel topics.

docs/src/cookbooks/cookbooks.md → 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.

docs/src/developers/developers.md → docs/src/developers.md

@@ -1,7 +1,3 @@
----
-sidebar_position: 4
----
-
 # Developer Documentation
 
 Tips and tricks for Chisel developers:

docs/src/explanations/explanations.md → docs/src/explanations.md

@@ -1,7 +1,3 @@
----
-sidebar_position: 2
----
-
 # Explanations
 
 Explanation documentation gives background and context.

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).
 

docs/src/installation.md

@@ -0,0 +1,174 @@
+---
+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 a Java Development Kit (JDK)_.
+More complex projects will require the user to install a 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 version 8 or newer; 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
+
+Note that Temurin is not part of the default apt repositories, so you will need to add the Eclipse Adoptium repository.
+
+Taken from the official [Temurin docs](https://adoptium.net/installation/linux/).
+Please note that installation on most systems will require superuser priviledges (`sudo`).
+You may need to prefix these commands with `sudo` including the `tee` commands following any pipes (`|`).
+
+```sh
+# Ensure the necessary packages are present:
+apt install -y wget gpg apt-transport-https
+
+# Download the Eclipse Adoptium GPG key:
+wget -qO - https://packages.adoptium.net/artifactory/api/gpg/key/public | gpg --dearmor | tee /etc/apt/trusted.gpg.d/adoptium.gpg > /dev/null
+
+# Configure the Eclipse Adoptium apt repository
+echo "deb https://packages.adoptium.net/artifactory/deb $(awk -F= '/^VERSION_CODENAME/{print$2}' /etc/os-release) main" | tee /etc/apt/sources.list.d/adoptium.list
+
+# Update the apt packages
+apt update
+
+# Install
+apt install temurin-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
+```
+
+<!-- TODO flesh this out -->
+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).

docs/src/resources/resources.md → 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).)

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

website/docusaurus.config.js

@@ -155,6 +155,7 @@ const config = {
         theme: prismThemes.github,
         darkTheme: prismThemes.dracula,
         additionalLanguages: [
+          'bash',
           // The Scala grammar extends the java one
           // prism requires manually loading java first
           'java',

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;

website/src/pages/index.js

@@ -17,8 +17,8 @@ function HomepageHeader() {
         <div className={styles.buttons}>
           <Link
             className="button button--secondary button--lg"
-            to="/docs">
-            Chisel Documentation
+            to="/docs/installation">
+            Getting Started
           </Link>
         </div>
       </div>