Change into educational example

[jackkoenig]

This PR is partially intended to spark discussion about what the chisel-template should be. Historically, I think there have been two competing concerns: education vs. template for repeated use. This PR is an attempt to pull more toward the education side since this is the example build to which we point new users. Others may disagree, but whatever we do I think the style of build.sbt I'm proposing here should exist somewhere.

Another opinion I have is that there really should not be a master vs. release of this repository. I think this should exist as purely a stable example (using normal releases). If someone wants to switch to the bleeding edge I think we should just encourage them to update the versions in this repository rather than checking out master instead of `release.

Another thought, perhaps we should move this to a g8 template since it is a little strange to start a project by inheriting a ton of git history. sbt new chipsalliance/chisel-template.g8 would give a better starting point with no git history (although we should obviously encourage users to use version control).

[ucbjrl]

The master branch isn't for users. It's for testing against the current master branches of the chisel ecosystem. It should probably be renamed to something like developerBranchOnlyForTestingAgainstChiselMaster. No non-developer should be using it.

[edwardcwang]

Maybe rename the current release branch to master, and the current master branch to chiselMaster or something?

[jackkoenig]

I see, so there are really 3 different concerns here:

1. Example for new comers
2. Clean template for starting new projects
3. Testing against master branches

I'm fine with leaving master or even the entire repo for (3). I am now thinking that a repository isn't really the right model for (2) since the repository history isn't really useful for the user; SBT g8 templates or just tarballs to curl seem better here. I feel (1) should be the same as (2), with the potential distinction that (1) has lots of comments in the build files while (2) can optionally leave it out.

Historically, it seems we've tried to make this repository (and in particularly, cloning it) serve all 3 cases. It could continue to do so, if we took a tarball release approach and encourage new users to just download the tarball.

Any thoughts? Am I making sense here?

[edwardcwang]

Github does have a feature where you can download the repo as a zip with no .git or git history. Maybe we can make that a link or something.

[schoeberl]

For educational usage in my opinion the setup is too long (= complicated). For a clean start, there is no need to support two Scala and two Java versions. Just 2.12 and JDK 8. And there are many files that may not really belong to a start. Do we really want to have some scalastyle here? I personally start with a single and short build.sbt and a single Chisel module. Maybe a Makefile to show the relevant sbt commands.

[jackkoenig]

I agree with @schoeberl (obviously since I made this PR). What do you think about changing the distribution mechanism for the starting template (or possible templates) to either sbt g8 or just tarballs?

For example, this already works with default Github source tarballs on release:

wget https://github.com/freechipsproject/chisel-template/archive/v3.1.1.tar.gz
tar xf v3.1.1.tar.gz 
cd chisel-template-3.1.1/

I very much agree with simplifying what we put in these template releases. A g8 template example would look something like:

sbt new freechipsproject/chisel-template.g8

This is similar to a recommended way of starting Scala projects: https://github.com/scala/scala-seed.g8

Also we can do both, and have multiple templates as long as we describe them on a docs page on the website for example.

[jackkoenig]

As evidenced by recent chisel-users thread (https://groups.google.com/u/1/g/chisel-users/c/io6TvQqPRH8), our flow for new people is not clear at all. I'm fine with master being for development, but some part of this or another repository should just be dead simple build.sbt like the one proposed here.

Do y'all think it should be this repo on the release branch? Another repo?

[schoeberl]

I agree with @edwardcwang that the "download as zip" form GitHub is an easy to use option for starters. This works for Windows and Unix users. wget/tar is for some too much to start.

The sbt new xx.g8 looks also like a promising start.

For the template itself, I would argue for the very minimum possible. Maybe we have two: 1.) super minimal and 2.) with all the bells and whistles.

For myself, I've created a minimal template. Ok, not super minimal as it also contains a Quartus project for an Intel FPGA. But the build.sbt is super lean (although it is not up to date for the latest Chisel version).

@jackkoenig agree on dead simple, and this is master and not some git checkout release.

Good that we discuss this. All initiatives to easy starting with Chisel are important.

[schoeberl]

Missed the link to my version of a minimal starting point: https://github.com/schoeberl/chisel-empty
I guess a super minimal HW design plus a simple test should be part of the template. Simpler than the current GCD example: just one design file and one test file. Which tester is up for discussion ;-)

Cheers,
Martin

[seldridge]

Just an FYI: I converted this to g8 a while back in https://github.com/seldridge/chisel-template.g8. You can test that to see what the workflow is like.

Previous discussion about g8 was here: #38

[edwardcwang]

To add to the template fracas... ;) https://github.com/edwardcwang/chisel-template-lite is a template that attempts to explain all the parts of itself, and comes with a mill template.

[jackkoenig]

Nix iotesters, pin versions

[jackkoenig]

Potentially only have dependency on chiseltest

[jackkoenig]

This has been done separately, see https://github.com/freechipsproject/chisel-template/tree/main which is the new default branch.