Adds Orangecrab starter project #38

enathang · 2025-10-28T12:56:17Z

Adds orangecrab starter project based on Felix's original orangecrab project.

One choice I'm not 100% on yet is the choice to include both Blink and accum as functionality in src/Blink.hs. I currently include both so that users can both make upload to see a change in their orangecrab (blink) and also have Hedgehog tests pre-setup for them (accum). However, this might confuse the user and blink and accum are separate functions that have no relation to one another. Thoughts welcome.

DigitalBrains1 · 2025-10-28T16:00:24Z

One choice I'm not 100% on yet is the choice to include both Blink and accum as functionality in src/Blink.hs. I currently include both so that users can both make upload to see a change in their orangecrab (blink) and also have Hedgehog tests pre-setup for them (accum). However, this might confuse the user and blink and accum are separate functions that have no relation to one another. Thoughts welcome.

You could do it similarly to how Christiaan did it with the DECA starter: Tests.DECA

DigitalBrains1

Thanks for adding another nice target!

This is quite a different setup than the other starter projects. I'd rather have more uniformity; I feel it should either be similar to simple or to simple-nix. If you feel those are inadequate, let's upgrade them all. I think it's kinda hard to document or support the starter projects if they each use a different project setup and even enable different extensions in the cabal file. It's also confusing to people when they switch dev boards.

projects/orangecrab/src/Orangecrab/Domain.hs

projects/orangecrab/Makefile

projects/orangecrab/src/Blink.hs

projects/orangecrab/src/RGB.hs

enathang · 2025-10-30T11:20:49Z

I've gone ahead and simplified the example code.

A couple opinionated choices I made:

The starter project does not automatically include Clash.Protocols or Clash.Cores. This might be a mistake, as we want to encourage new users to use these features.
I tried to balance both use cases of: orange crab by itself, and orange crab with breakout board. I wanted to show off a topEntity that had both input and output, because it avoids a pure () in the topEntity, which I think is confusing. I also think an interactive example is more fun. However, the only builtin input the orangecrab has is the reset button, which I can't map to anything.

My solution was to make the example work without needing input (just cycle LEDs), but if pin B8 is driven high (corresponding to breakout PMOD 1_4), then the user can play with the orangecrab example. That way, the example still works without the breakout board, but it becomes interactive with the breakout board (or the user can drive the pin themselves).
3) The nix flake can optionally be used to pull in the tools required by makefile. However, I think it still also accidentally pulls in Haskell stuff. So, I still have to further trim down the flake.nix.

I'm still working on writing a few more comments and updating README, but feedback welcome.

DigitalBrains1 · 2025-10-30T12:08:15Z

[edit] I think this post I made is too unnuanced, please read my next message for a more nuanced take [/edit]

The starter project does not automatically include Clash.Protocols or Clash.Cores. This might be a mistake, as we want to encourage new users to use these features.

I really think we should first make a release of those packages before we encourage new users to use those features... they're welcome to them, but they are also experimental and without any API guarantees. Is this something that was discussed? I don't remember hearing this before.

I hope I'll have time to do a bit more review sometime soon.

enathang · 2025-10-30T12:14:12Z

No, it wasn't discussed or anything. Personally, I'm a strong proponent of pushing them even while they're in the experimental phase.

But, leaving it out makes this PR a bit easier, so no complaints on my end.

DigitalBrains1 · 2025-10-30T12:16:52Z

I was actually rephrasing my post because I was unhappy with it. But now that you answered, I'll put it here.

I'm a bit conflicted, since we haven't released these packages and they are still experimental and without API guarantees.

There's definitely something to say for just offering it to users with a bunch of caveats, even before a release. We do do this in a sense, as they're right at the top of our Ecosystem page, including instructions for how to install them in the starter project.

All the things in the ecosystem page are interesting, so giving our ecosystem page (which contains the instructions to add the packages!) a more prominent place in the README for the starter projects seems very sensible.

We might need to be a bit more explicit about the stability of clash-cores. [edit] Ah no, wait, we have the under construction right at the top :-). I don't think my brain is firing on all cylinders to be honest. [/edit]

jaschutte · 2025-10-31T13:52:31Z

The nix flake can optionally be used to pull in the tools required by makefile. However, I think it still also accidentally pulls in Haskell stuff. So, I still have to further trim down the flake.nix.

So do you do not want to pull in any Haskell dependencies via the Nix flake? Why not? If someone already uses Nix, why not allow them to use the Nix cache for the Haskell dependencies?

DigitalBrains1

You forgot to run render.hs.

Could you add Stack support?

I still have more feedback, but there's no more week left now. I'll continue later; this is already a lot!

projects/orangecrab/LICENSE

projects/orangecrab/src/Orangecrab/Domain.hs

projects/orangecrab/README.md

projects/orangecrab/Makefile

projects/orangecrab/README.md

projects/orangecrab/{{name}}.cabal

DigitalBrains1

Ah woops I'm requesting changes with my review immediately above but forgot to select that again after my choice got reset through a little oopsie that cost me tons of time...

DigitalBrains1 · 2025-11-01T09:18:01Z

Thanks a lot for all your work on the nice starter project! It has a well-written instructive README, it is easy to use and it adds support for a very affordable dev board. You could say a starter dev board.

Note that all my little style suggestions to the README could quickly be applied with the "Add suggestion to batch" button and then the batch can be committed. However, GitHub has a new view for the Files tab and it doesn't seem to support that. If you want to be able to add suggestions to a batch, go to the Files tab and in the top right corner find the "Preview - Switch back - Feedback" text. Click "Switch back", and you'll get back to the old view that has "Add suggestion to batch". Of course if instead of "Preview - Switch back" it says "✨ Try the new experience", then you're already in the old view.

I wrote:

Could you add Stack support?

And I thought it'd be a matter of copying the stack.yaml from simple and add a few entries to the .gitignore. But that's not correct! We still have the Makefile then which doesn't actually use Stack. There's however two reasons I'd like to have Stack in there. First of all, currently, if you do stack new my-clash-project clash-lang/orangecrab, you get a whole bunch of warnings that are confusing to the user. Secondly, our recommended way of using Clash is with a starter project and Stack. So I'd like our actually recommended setup to work. Don't bother updating Clash 1.8.2 in stack.yaml to 1.8.3. Somehow, we forgot to do that when we released 1.8.3 even though it's one of the points in the checklist for releases. But we'll have a 1.8.4 Real Soon Now™ so let's tackle it then.

Perhaps you can add this to build.cfg:

USE_STACK=yes

and then use that var in the Makefile to switch between stack and cabal.

projects/orangecrab/build.cfg

projects/orangecrab/Makefile

lmbollen · 2025-11-03T07:38:48Z

The nix flake can optionally be used to pull in the tools required by makefile. However, I think it still also accidentally pulls in Haskell stuff. So, I still have to further trim down the flake.nix.

So do you do not want to pull in any Haskell dependencies via the Nix flake? Why not? If someone already uses Nix, why not allow them to use the Nix cache for the Haskell dependencies?

This was discussed offline. The main reason is that this is a stack template, so it's tailored to stack users. We don't want to run into the situation where we offer an accessible way to obtain the required synthesis tools(flake.nix) that would pull those users out of their ecosystem.

For us the alternative was not offering a flake.nix at all.

We can later still make a template for nix users similar to simple-nix.

kleinreact · 2025-11-06T18:30:53Z

We might need to be a bit more explicit about the stability of clash-cores. [edit] Ah no, wait, we have the under construction right at the top :-). I don't think my brain is firing on all cylinders to be honest. [/edit]

Maybe not the right place to discuss this, but we also still ship clash-cores on the 1.8 branch and publish it with the compiler, e.g. its still part of the sources recently released at https://github.com/clash-lang/clash-compiler/releases/tag/v1.8.4 (yes: there is a clash-cores-1.8.4 inside, which is not marked experimental).

NB: some of my private projects even still rely on this fact, as they only need basic stuff like the UART and pulling that from the release package is much more convenient than switching to the new repository and checking it out from there instead.

DigitalBrains1 · 2025-11-07T11:12:42Z

Ah, yes, you should definitely not consider that a released clash-cores.

…d value

Since we dropped a step, it started at 02-hdl. Renumber to start at 01-hdl and on.

And make the tests have the same layout as there

We don't have one in the other starter projects, we specify 2-BSD not MIT, and people might use any license they choose.

Added are /_build/ *.local The latter came in the place of the overlapping /cabal.project.local.

Also add some useful information and do some copyediting.

An alternative would be to use `vXilinxSystem` instead of `vSystem` as the basis for the record update; but I think this is more confusing than helpful even though it's shorter.

The whole repo is CC0.

DigitalBrains1

(You might already have noticed, but the CI scripts should match on orangecrab.hsfiles ending in an s, not .hsfile)

enathang requested a review from lmbollen October 28, 2025 12:56

DigitalBrains1 reviewed Oct 28, 2025

View reviewed changes

enathang requested a review from DigitalBrains1 October 30, 2025 11:21

DigitalBrains1 reviewed Oct 31, 2025

View reviewed changes

DigitalBrains1 requested changes Oct 31, 2025

View reviewed changes

DigitalBrains1 reviewed Nov 1, 2025

View reviewed changes

projects/orangecrab/build.cfg Outdated Show resolved Hide resolved

DigitalBrains1 reviewed Nov 2, 2025

View reviewed changes

projects/orangecrab/Makefile Outdated Show resolved Hide resolved

projects/orangecrab/Makefile Outdated Show resolved Hide resolved

DigitalBrains1 reviewed Nov 2, 2025

View reviewed changes

projects/orangecrab/Makefile Outdated Show resolved Hide resolved

enathang added 12 commits December 15, 2025 16:46

Adds orangecrab starter project

b0c4cb2

Updates README and fixes nix flake

f078d33

Updates .gitignore

4ad46e9

Migrates clash away from clash-proxy to symlink to simple-project

4f49b9e

Bugfix: removes unused clash-proxy from cabal.project

995cb0e

Simplifies blink example for readability

46b0707

Inits new project for orangecrab-nix

fba5aab

Update proj name from orangecrab to {{name}} for stack

d73d462

Makes orangecrab template use {{name}} everywhere instead of hardcode…

aba8b84

…d value

Removes haskell from nix flake

423c3ee

Uppercase Makefile name

520858a

Adds initial draft of blink unit test

1bfb54e

enathang and others added 13 commits December 15, 2025 16:46

Update comments from Peter feedback

7efa663

Updates Makefile with Peter's proposed change

f610a9a

adds orangecrab.hsfiles

e0baa3f

Remove the Clash step from the Makefile

ea5a88d

Renumber build dirs

b3e1914

Since we dropped a step, it started at 02-hdl. Renumber to start at 01-hdl and on.

Adopt .cabal file from simple project

b73be20

And make the tests have the same layout as there

Add stack.yaml

59eb263

Remove LICENSE

0e73625

We don't have one in the other starter projects, we specify 2-BSD not MIT, and people might use any license they choose.

Adopt/adapt simple's gitignore

acc06ad

Added are /_build/ *.local The latter came in the place of the overlapping /cabal.project.local.

Merge in stuff from simple README

3e6a1d9

Also add some useful information and do some copyediting.

Change domain to sync resets

c0cbdbe

An alternative would be to use `vXilinxSystem` instead of `vSystem` as the basis for the record update; but I think this is more confusing than helpful even though it's shorter.

Rerun render.hs

1d238bf

Makefile formatting fixes

7da0822

enathang force-pushed the orangecrab branch from 50c7b56 to 7da0822 Compare December 17, 2025 13:20

DigitalBrains1 and others added 5 commits December 17, 2025 16:27

README: no Nix, no issues with init values

8de60c4

Fix polarity issue in driveRGB

0ed4473

Get rid of license headers

9d99efb

The whole repo is CC0.

Remove Nix stuff

ee1d49a

[skip-ci] Re-runs ./render

e31ab45

enathang requested a review from DigitalBrains1 December 18, 2025 14:17

enathang and others added 5 commits December 18, 2025 15:29

Fixes unit test failing

36867fe

README: add missing closing parenthesis

f1bc9b8

Fix somewhat misleading test step

e6f4a7d

Invoke ./render.hs

3599a91

Fixes ci for orangecrab

a94ae45

enathang force-pushed the orangecrab branch from e5ac8e9 to a94ae45 Compare December 18, 2025 15:03

DigitalBrains1 approved these changes Dec 18, 2025

View reviewed changes

Fix typo in .ci bash scripts that was failing orangecrab ci

c16f251

enathang merged commit f1f256d into master Jan 14, 2026
17 checks passed

enathang deleted the orangecrab branch January 14, 2026 13:08

Adds Orangecrab starter project #38

Adds Orangecrab starter project #38

Uh oh!

Conversation

enathang commented Oct 28, 2025

Uh oh!

DigitalBrains1 commented Oct 28, 2025

Uh oh!

DigitalBrains1 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

enathang commented Oct 30, 2025

Uh oh!

DigitalBrains1 commented Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

enathang commented Oct 30, 2025

Uh oh!

DigitalBrains1 commented Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jaschutte commented Oct 31, 2025

Uh oh!

DigitalBrains1 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

DigitalBrains1 left a comment

Choose a reason for hiding this comment

Uh oh!

DigitalBrains1 commented Nov 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lmbollen commented Nov 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kleinreact commented Nov 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

DigitalBrains1 commented Nov 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

DigitalBrains1 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

DigitalBrains1 commented Oct 30, 2025 •

edited

Loading

DigitalBrains1 commented Oct 30, 2025 •

edited

Loading

DigitalBrains1 commented Nov 1, 2025 •

edited

Loading

lmbollen commented Nov 3, 2025 •

edited

Loading

kleinreact commented Nov 6, 2025 •

edited

Loading

DigitalBrains1 commented Nov 7, 2025 •

edited

Loading