This is a static-site-generator based on bridgetown (jekyll fork). It serves as a frontend for an experimental tool for performing long running benchmarks of Bitcoin Core, found at https://github.com/bitcoin-dev-tools/benchcoin
You will need ruby, I recommend using rbenv
to install the version specified in the
.ruby-version
file.
You will also need npm, which you can get through your package manager, and you will need yarn:
npm install yarn🫴 Note: You may need to do `rbenv rehash` if you encounter errors where
rbenv can't find newly installed binaries in your $PATH, like yarn.
yarn install # install js deps
bundle install # install ruby gemsgit clone --single-branch --branch gh-pages git@github.com:bitcoin-dev-tools/benchcoin.git temp_benchcoin
mkdir -p src/benchcoin
mv temp_benchcoin/results/* src/benchcoin/
rm -rf temp_benchcoinbin/bridgetown startbin/bridgetown start will print the address in your console where the
webserver is serving the built site, it will watch for changes and rebuild
immediately.
The vast majority of the files and folders here are boilerplate / scaffolding, so I want to highlight what I think are the relevant parts:
The logic that handles construction of
"resources" (every PR and run
is a 'resource') from the data generated by benchcoin is in
plugins/builder/pull_requests_builder.rb.
All that is important that remains is the templating and components for the
views that we generate and is all located in src/. For toplevel pages like
the indexes of runs and pulls, an ERB template file is placed in
/src/.
The layouts used to render individual resources are located in /src/_layouts,
and there are two three competing abstractions for making views "modular"/DRY:
'layouts', 'partials' and "components".
Start with layout, if a part of the layout becomes too complicated or is worth reusing make it a component.
Avoid using 'partials' (/src/_partials) entirely, in theory, partials should
be used as a sort of "dumb" component that doesn't require any logic and is
pure document content that you want to insert in another document, but in
practice this is rare and overlaps with layouts too much.
Layouts, in /src/_layouts are jekyll/bridgetown's homegrown abstraction, these seem
to be inverted partials. Where, e.g. instead of including the header
partial at the top and the footer partial at the bottom of your document, you
write a layout that has a header and footer with a <% yield %> clause in the middle,
and mark your document as a user of that layout, and it's contents will be
inserted at the yield statement.
Because we are generating fake resources with the resource builder, we are kind-of forced into using layouts as the view of individual resources we generate.
Components are partials that you can pass variables1 and that can process
them before handing things off to a layout file. Each component consists of a
component.erb template that gets included when you render the component in a
document, and a component.rb file that defines a subclass2 of
Bridgetown::Component with an initialize method that takes the arguments
passed in the render call and sets up the instance variables (@var) that
will be available in the template.
Using Bridgetown components at present because there was some trouble getting Gtihub's ViewComponents to work, but for most use cases they are basically identical.
In the future, this could be an API, but I don't know what shape that should take.
The PullRequestBuilder expects there to be a folder src/benchcoin: with the
following layout:
📂src/benchcoin
- 📂pr-1
- 📂{{github-run-id}}
- [ ...results generated by bitcoin-dev-tools/benchcoin... ]
- 📁pr-2
- [....]
7BFA
- 📂pr-{{pr-number}}
- 📁{{github-run-id}}
- 📁{{github-run-id}}
- 📁{{github-run-id}}
- 📁{{github-run-id}}
Currently, the layout of src/benchcoin is identical to the results
folder
of the gh-pages branch of
bitcoin-dev-tools/benchcoin.
More details can be found in this repo's gh-pages script
(.github/workflows/gh-pages.yml) this repo uses to
generate the Github pages hosted instance, I will move this script to a justfile
to simplify local development.
ERB is a templating system for
mixing Ruby expressions with arbitrary plain text documents, where anything
inside of <% %> gets evaluated silently, and the result or return value of
evaluating the expression inside of <%= %> is inserted into the document.
Control-flow applies outside of the ruby expressions, e.g.:
# `index.erb`
<% if true %>
<h1>The statement was true!</h1>
<% else %>
<h1>The statement was false!</h1>
<% end %>would generate the html file:
# `index.html`
<h1>The statement was true!</h1>Bridgetown serves as a nice middle ground between hand rolling github actions scripts for generating HTML from benchmark results and a full web-app framework like Ruby on Rails, it even uses a lot of the same abstractions and libraries as Ruby on Rails, like erb templates and Github's ViewComponent library, meaning that if something more full-fat is ever needed, a lot of what's here could be reused.