102 lines
4.8 KiB
Markdown
102 lines
4.8 KiB
Markdown
Chisel Project Template
|
|
=======================
|
|
|
|
You've done the [Chisel Bootcamp](https://github.com/freechipsproject/chisel-bootcamp), and now you
|
|
are ready to start your own Chisel project. The following procedure should get you started
|
|
with a clean running [Chisel3](https://www.chisel-lang.org/) project.
|
|
|
|
## Make your own Chisel3 project
|
|
|
|
### Dependencies
|
|
|
|
#### JDK 8 or newer
|
|
|
|
We recommend LTS releases Java 8 and Java 11. You can install the JDK as recommended by your operating system, or use the prebuilt binaries from [AdoptOpenJDK](https://adoptopenjdk.net/).
|
|
|
|
#### SBT or mill
|
|
|
|
SBT is the most common built tool in the Scala community. You can download it [here](https://www.scala-sbt.org/download.html).
|
|
mill is another Scala/Java build tool without obscure DSL like SBT. You can download it [here](https://github.com/com-lihaoyi/mill/releases)
|
|
|
|
### How to get started
|
|
|
|
#### Create a repository from the template
|
|
|
|
This repository is a Github template. You can create your own repository from it by clicking the green `Use this template` in the top right.
|
|
Please leave `Include all branches` **unchecked**; checking it will pollute the history of your new repository.
|
|
For more information, see ["Creating a repository from a template"](https://docs.github.com/en/free-pro-team@latest/github/creating-cloning-and-archiving-repositories/creating-a-repository-from-a-template).
|
|
|
|
#### Wait for the template cleanup workflow to complete
|
|
|
|
After using the template to create your own blank project, please wait a minute or two for the `Template cleanup` workflow to run which will removes some template-specific stuff from the repository (like the LICENSE).
|
|
Refresh the repository page in your browser until you see a 2nd commit by `actions-user` titled `Template cleanup`.
|
|
|
|
|
|
#### Clone your repository
|
|
|
|
Once you have created a repository from this template and the `Template cleanup` workflow has completed, you can click the green button to get a link for cloning your repository.
|
|
Note that it is easiest to push to a repository if you set up SSH with Github, please see the [related documentation](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/connecting-to-github-with-ssh). SSH is required for pushing to a Github repository when using two-factor authentication.
|
|
|
|
```sh
|
|
git clone git@github.com:%REPOSITORY%.git
|
|
cd %NAME%
|
|
```
|
|
(The variables wrapped in `%` will be filled in by the template cleanup) <!-- #REMOVE-ON-CLEANUP# -->
|
|
|
|
#### Set project organization and name in build.sbt
|
|
|
|
The cleanup workflow will have attempted to provide sensible defaults for `ThisBuild / organization` and `name` in the `build.sbt`.
|
|
Feel free to use your text editor of choice to change them as you see fit.
|
|
|
|
#### Clean up the README.md file
|
|
|
|
Again, use you editor of choice to make the README specific to your project.
|
|
|
|
#### Add a LICENSE file
|
|
|
|
It is important to have a LICENSE for open source (or closed source) code.
|
|
This template repository has the Unlicense in order to allow users to add any license they want to derivative code.
|
|
The Unlicense is stripped when creating a repository from this template so that users do not accidentally unlicense their own work.
|
|
|
|
For more information about a license, check out the [Github Docs](https://docs.github.com/en/free-pro-team@latest/github/building-a-strong-community/adding-a-license-to-a-repository).
|
|
|
|
#### Commit your changes
|
|
```sh
|
|
git commit -m 'Starting %NAME%'
|
|
git push origin main
|
|
```
|
|
|
|
### Did it work?
|
|
|
|
You should now have a working Chisel3 project.
|
|
|
|
You can run the included test with:
|
|
```sh
|
|
sbt test
|
|
```
|
|
|
|
You should see a whole bunch of output that ends with something like the following lines
|
|
```
|
|
[info] Tests: succeeded 1, failed 0, canceled 0, ignored 0, pending 0
|
|
[info] All tests passed.
|
|
[success] Total time: 5 s, completed Dec 16, 2020 12:18:44 PM
|
|
```
|
|
If you see the above then...
|
|
|
|
### It worked!
|
|
|
|
You are ready to go. We have a few recommended practices and things to do.
|
|
|
|
* Use packages and following conventions for [structure](https://www.scala-sbt.org/1.x/docs/Directories.html) and [naming](http://docs.scala-lang.org/style/naming-conventions.html)
|
|
* Package names should be clearly reflected in the testing hierarchy
|
|
* Build tests for all your work
|
|
* Read more about testing in SBT in the [SBT docs](https://www.scala-sbt.org/1.x/docs/Testing.html)
|
|
* This template includes a [test dependency](https://www.scala-sbt.org/1.x/docs/Library-Dependencies.html#Per-configuration+dependencies) on [chiseltest](https://github.com/ucb-bar/chisel-testers2), this is a reasonable starting point for most tests
|
|
* You can remove this dependency in the build.sbt file if you want to
|
|
* Change the name of your project in the build.sbt file
|
|
* Change your README.md
|
|
|
|
## Problems? Questions?
|
|
|
|
Check out the [Chisel Users Community](https://www.chisel-lang.org/community.html) page for links to get in contact!
|