Add `contrib/justfile` containing useful development workflow commands.

casey commented at 9:22 pm on November 14, 2024: contributor

Add contrib/justfile containing useful development workflow commands.

Just recipes can be run by symlinking contrib/justfile into the repository root:

ln -s contrib/justfile justfile

And running:

just RECIPE

From any subdirectory.

Also add /justfile to .gitignore, to ignore the symlink into the repository root.

just is command runner with make-like syntax. It is not a build system, and only serves as convenient way of saving and running commands. It is available here:

https://github.com/casey/just/

Added in contrib/justfile, since just is a large, unreviewed dependency. Developers considering using just should make sure to take this into consideration.

I feel a bit uncomfortable opening a PR which adds a justfile, since I wrote and maintain just, but whenever I work on Bitcoin Core, I always wind up adding a justfile to make running and remembering commands easy, and I think others might find it useful as well.

I thought that adding it to contrib/justfile would be best. I try to maintain just to high standards, but those standards are those of an open source developer tool project, not a highly security sensitive project like Bitcoin Core, so putting it in contrib signals that users should take that into consideration before using just.

just supports a number of features that make doesn’t, and in general is less error prone:

Recipes can take arguments
No .PHONY needed
Good error messages, both for runtime and syntax errors
Uses {{…}} for interpolation instead of $, so no need to $$
List recipes with just --list
Completion scripts for most shells

A justfile serves as a convenient way to save and run commands, and as a form of documentation of what commands developers are likely to need when working on the project.

I included configure, build, clean, test, and watch commands, along with d and cli commands which run the built bitcoind and bitcoin-cli in regtest mode, forwarding any additional arguments.

Add contrib/justfile

Add a `justfile` containing useful development workflow commands.

Just recipes can be run by symlinking `contrib/justfile` into the
repository root:

    ln -s contrib/justfile justfile

And running:

    just RECIPE

Also add `/justfile` to `.gitignore`, to ignore symlinks.

`just` is command runner with make-like syntax. It is not a build
system, and only serves as convenient way of saving and running
commands. It is available here:

    https://github.com/casey/just/

Added in `contrib/justfile`, since `just` is a large, unreviewed
dependency. Developers considering using `just` should make sure to take
this into consideration.

ccea33e080

DrahtBot commented at 9:22 pm on November 14, 2024: contributor

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Code Coverage & Benchmarks

For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/31292.

Reviews

See the guideline for information on the review process.

Type	Reviewers
Concept NACK	achow101

If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update.

Conflicts

Reviewers, this pull request conflicts with the following ones:

#30469 (index: Fix coinstats overflow and introduce index versioning by fjahr)

If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

achow101 commented at 9:35 pm on November 14, 2024: member

Concept NACK

We generally do not include files that are specific to particular people’s development environments such as IDE configurations, and this seems to be pretty close to that kind of thing. Nor do we add to our gitignore files that are specific to particular people’s workflows as those should be part of their global .gitignore.

casey commented at 9:38 pm on November 14, 2024: contributor

Concept NACK

We generally do not include files that are specific to particular people’s development environments such as IDE configurations, and this seems to be pretty close to that kind of thing. Nor do we add to our gitignore files that are specific to particular people’s workflows as those should be part of their global .gitignore.

Fair enough! I will say that I think this is generally useful to anyone who works in the terminal, and serves as a generally useful source of documentation for which commands to run.

One issue with adding justfile to a global .gitignore is that in most repos with a justfile, it is not ignored. But there’s always the repo-specific .git/info/exclude for adding repo-specific ignores.

in contrib/justfile:13 in ccea33e080

 8+
 9+build: configure
10+  cmake --build build -j {{ n }}
11+
12+configure:
13+  @[[ -d build ]] || cmake -B build

maflcko commented at 8:11 am on November 15, 2024:

Not sure about adding this. It seems more indirections to type just configure -DCMAKE_C_COMPILER='clang' -DCMAKE_CXX_COMPILER='clang++' ..etc... than just cmake -B build -DCMAKE_C_COMPILER='clang' -DCMAKE_CXX_COMPILER='clang++' ...etc... directly.

In the end, I think for this to be useful, the developer or user would have to write the justfile themselves. Trying to offer one (even if it is just an example) is almost guaranteed to only find use by a single person.

casey commented at 0:27 am on November 17, 2024:

More advanced commands and configuration would definitely require departing from the commands in the justfile. However, for someone just getting started, for simple commands, and using the given commands as a starting point to write your own, it’s still very useful.

TheCharlatan commented at 9:10 am on November 17, 2024:

We already have the cmake presets for making it a bit easier to get started and the user can bring their own CmakeUserPresets.json. It is seldom that I am still typing out a full cmake command.

casey commented at 6:44 pm on November 17, 2024:

cmake presets only work for cmake commands, however there are a bunch of commands one should know for working on core.

willcl-ark commented at 12:04 pm on November 18, 2024: member

I really enjoy making justfiles for projects I work on.

And, whilst I would love to see some kind of community justfile added to this project, I can appreciate the hesitation to do so per the rationale given by @achow101 above.

I’ve therefore taken a different approach myself, hosting a justfile at https://github.com/bitcoin-dev-tools/dotfiles which is designed to sit one directory higher than this repository’s code, specifically so that it doesn’t interfere with the source directory (and allows things like git clean -dfx to be run, which for me is now much more common post-cmake).

If this PR doesn’t get any traction here, I’d welcome contributions/improvements to that file over there, and perhaps in the future we could link to it from this project or publicize it in some other way.

In the end, I think for this to be useful, the developer or user would have to write the justfile themselves. Trying to offer one (even if it is just an example) is almost guaranteed to only find use by a single person.

Just looking at the differences between this PR and my justfile highlights this problem. Although that’s not to say that I don’t think there’s a world we we could supply a base justfile with some universal/“essential” commands. This type of thing has been common in makefiles (and contrib scripts) for a long time.

Add contrib/justfile containing useful development workflow commands. #31292

Code Coverage & Benchmarks

Reviews

Conflicts

Add `contrib/justfile` containing useful development workflow commands. #31292