gnolang
docs(make): improve and centralize make help output
Summary
This PR provides a minor quality-of-life improvement for new Gno developers by enhancing make help output across the project.
Highlights
make helpnow displays inline comments appended to target lines, offering clear, one-line explanations for each Make target.make -C contribs help:- Expands wildcard subdirectories,
- Includes their annotated
make helpoutputs, - Extracts the first line of each
README.mdto display a brief description of each tool.
- Preserves the existing self-scraping help behavior—just with more context and clarity.
No functional changes—just improved discoverability and documentation for contributors.
🛠 PR Checks Summary
All Automated Checks passed. ✅
Manual Checks (for Reviewers):
- [ ] IGNORE the bot requirements for this PR (force green CI check)
- [x] The pull request description provides enough details (checked by @thehowl)
Read More
🤖 This bot helps streamline PR reviews by verifying automated checks and providing guidance for contributors and reviewers.
✅ Automated Checks (for Contributors):
🟢 Maintainers must be able to edit this pull request (more info) 🟢 Pending initial approval by a review team member, or review from tech-staff
☑️ Contributor Actions:
- Fix any issues flagged by automated checks.
- Follow the Contributor Checklist to ensure your PR is ready for review.
- Add new tests, or document why they are unnecessary.
- Provide clear examples/screenshots, if necessary.
- Update documentation, if required.
- Ensure no breaking changes, or include
BREAKING CHANGEnotes. - Link related issues/PRs, where applicable.
☑️ Reviewer Actions:
- Complete manual checks for the PR, including the guidelines and additional checks if applicable.
📚 Resources:
Debug
Automated Checks
Maintainers must be able to edit this pull request (more info)
If
🟢 Condition met └── 🟢 And ├── 🟢 The base branch matches this pattern: ^master$ └── 🟢 The pull request was created from a fork (head branch repo: loren-osborn/gno)Then
🟢 Requirement satisfied └── 🟢 Maintainer can modify this pull requestPending initial approval by a review team member, or review from tech-staff
If
🟢 Condition met └── 🟢 And ├── 🟢 The base branch matches this pattern: ^master$ └── 🟢 Not (🔴 Pull request author is a member of the team: tech-staff)Then
🟢 Requirement satisfied └── 🟢 If ├── 🟢 Condition │ └── 🟢 Or │ ├── 🔴 At least 1 user(s) of the organization reviewed the pull request (with state "APPROVED") │ ├── 🟢 At least 1 user(s) of the team tech-staff reviewed pull request │ └── 🔴 This pull request is a draft └── 🟢 Then └── 🟢 And ├── 🟢 Not (🔴 This label is applied to pull request: review/triage-pending) └── 🟢 At least 1 user(s) of the team tech-staff reviewed pull requestManual Checks
**IGNORE** the bot requirements for this PR (force green CI check)
If
🟢 Condition met └── 🟢 On every pull requestCan be checked by
- Any user with comment edit permission
The pull request description provides enough details
If
🟢 Condition met └── 🟢 And ├── 🟢 Not (🔴 Pull request author is a member of the team: core-contributors) └── 🟢 Not (🔴 Pull request author is user: dependabot[bot])Can be checked by
- team core-contributors
This is still an early proof of concept. I welcome feedback.
while I might have liked doxygen style comments for each target, this implementation is significantly less complex than would be required for multiple-line prefixed comment block parsing.
FYI: work not yet finished:
comments should be added to all relevant targets
The makefile looks too complex. Not sure how much it can be useful, but it looks like something we should have in an external script or binary to keep the makefiles simple.
The makefile looks too complex. Not sure how much it can be useful, but it looks like something we should have in an external script or binary to keep the makefiles simple.
You raise a valid point. I’ll admit I may be a bit too comfortable with complex Makefiles for my own good. I’ll likely finish this PR regardless—as a learning exercise—but I was hoping it might prove useful to others as well.
For the sake of discussion, here’s a side-by-side comparison of the output before and after this change, using the two directories I’ve completed so far:
Before:
% make
Available make commands:
fmt
help
install
install.gno
install.gnodev
install.gnokey
lint
test
test.components
tidy
% make -C contribs
Available make commands:
fmt
help
install
install.%
install_all
lint
lint.%
test
test.%
tidy
%
After:
% make
Available make commands:
fmt <-- Format components Tendermint2, GnoVM, Gno.land and examples
help <-- Print this help message
install.gno <-- Install Gno
install.gnodev <-- Install GnoDev
install.gnokey <-- Install GnoKey
install <-- Install GnoKey, Gno and GnoDev
lint <-- Lint all non-vendor *.go and *.gno code recursively
test.components <-- Test components Tendermint2, GnoVM, Gno.land, examples and misc
test <-- Test everything (for now, same as test.components)
tidy <-- Run 'go mod tidy' in all Go modules within the `misc` directory
Sub-directories with make targets:
* /Applications/Xcode.app/Contents/Developer/usr/bin/make -C contribs
/Applications/Xcode.app/Contents/Developer/usr/bin/make -C docs
* /Applications/Xcode.app/Contents/Developer/usr/bin/make -C examples
* /Applications/Xcode.app/Contents/Developer/usr/bin/make -C gno.land
* /Applications/Xcode.app/Contents/Developer/usr/bin/make -C gnovm
* /Applications/Xcode.app/Contents/Developer/usr/bin/make -C misc
* /Applications/Xcode.app/Contents/Developer/usr/bin/make -C tm2
* Is documented with a `help` target.
% make -C contribs
Available make commands:
fmt <-- Format all Go files in this directory and subdirectories
help <-- Print this help message
install <-- Print instructions for installing one or all subpackages
install.github-bot <-- Install subpackage github-bot (GitHub Bot)
install.gnodev <-- Install subpackage gnodev (Your Gno Development Companion)
install.gnofaucet <-- Install subpackage gnofaucet (Start a local faucet)
install.gnogenesis <-- Install subpackage gnogenesis (CLI tool for managing the Gnoland blockchain's `genesis.json` file)
install.gnohealth <-- Install subpackage gnohealth (Gno Health Check CLI)
install.gnokeykc <-- Install subpackage gnokeykc (CLI tool enhancing gnokey for system keychain integration)
install.gnomd <-- Install subpackage gnomd (Terminal Markdown Viewer for Gno Documentation)
install.gnomigrate <-- Install subpackage gnomigrate (CLI Gno legacy data migration tool.)
install_all <-- Install all subpackages
lint <-- Lint all subpackages
lint.github-bot <-- Lint subpackage github-bot (GitHub Bot)
lint.gnodev <-- Lint subpackage gnodev (Your Gno Development Companion)
lint.gnofaucet <-- Lint subpackage gnofaucet (Start a local faucet)
lint.gnogenesis <-- Lint subpackage gnogenesis (CLI tool for managing the Gnoland blockchain's `genesis.json` file)
lint.gnohealth <-- Lint subpackage gnohealth (Gno Health Check CLI)
lint.gnokeykc <-- Lint subpackage gnokeykc (CLI tool enhancing gnokey for system keychain integration)
lint.gnomd <-- Lint subpackage gnomd (Terminal Markdown Viewer for Gno Documentation)
lint.gnomigrate <-- Lint subpackage gnomigrate (CLI Gno legacy data migration tool.)
test <-- Test all subpackages
test.github-bot <-- Test subpackage github-bot (GitHub Bot)
test.gnodev <-- Test subpackage gnodev (Your Gno Development Companion)
test.gnofaucet <-- Test subpackage gnofaucet (Start a local faucet)
test.gnogenesis <-- Test subpackage gnogenesis (CLI tool for managing the Gnoland blockchain's `genesis.json` file)
test.gnohealth <-- Test subpackage gnohealth (Gno Health Check CLI)
test.gnokeykc <-- Test subpackage gnokeykc (CLI tool enhancing gnokey for system keychain integration)
test.gnomd <-- Test subpackage gnomd (Terminal Markdown Viewer for Gno Documentation)
test.gnomigrate <-- Test subpackage gnomigrate (CLI Gno legacy data migration tool.)
tidy <-- Run 'go mod tidy' in all Go modules within this directory and subdirectories
Sub-directories with make targets:
/Applications/Xcode.app/Contents/Developer/usr/bin/make -C contribs/github-bot
/Applications/Xcode.app/Contents/Developer/usr/bin/make -C contribs/gnodev
/Applications/Xcode.app/Contents/Developer/usr/bin/make -C contribs/gnofaucet
/Applications/Xcode.app/Contents/Developer/usr/bin/make -C contribs/gnogenesis
/Applications/Xcode.app/Contents/Developer/usr/bin/make -C contribs/gnohealth
/Applications/Xcode.app/Contents/Developer/usr/bin/make -C contribs/gnokeykc
/Applications/Xcode.app/Contents/Developer/usr/bin/make -C contribs/gnomd
/Applications/Xcode.app/Contents/Developer/usr/bin/make -C contribs/gnomigrate
%
That said, this might be too much information for a new contributor at once.
@moul – I appreciate you taking a look. I agree this is more complex than ideal, and I’m still not convinced the value justifies the overhead. There’s also quite a bit of boilerplate here that could probably be factored out into a shared script to simplify the Makefiles.
Either way, I look forward to wrapping this up and turning my attention to a project with more lasting impact.
Hi @moul,
I'm not sure if this is quite what you had in mind. The logic is essentially the same as before, but now centralized in misc/makeHelpMsgs.mk. While the result is only slightly more concise, it avoids repeating the same logic across seven different files—which I think is a worthwhile improvement.
It does introduce light use of Make functions, which might make it a bit harder to read at first glance, but in exchange, all of the comment scraping and formatting logic now lives in one place.
That said, if you feel this direction complicates things more than it helps, I’m happy to revisit or revert it.
Best regards, @loren-osborn
P.S. I still have to add the applicable comments to: examples/Makefile, gno.land/Makefile, gnovm/Makefile, misc/Makefile and tm2/Makefile
Codecov Report
All modified and coverable lines are covered by tests :white_check_mark:
:loudspeaker: Thoughts on this report? Let us know!
![codecov[bot] avatar](https://avatars.githubusercontent.com/in/254?v=4 "Published by a pub.dev verified publisher"){kind=small}
Hi @loren-osborn . Can you please fix the failed check for "PR Title Linter"?
Hi @loren-osborn . Can you please fix the failed check for "PR Title Linter"?
Hi @Jefft0 — thanks! I’ve updated the title to use docs, since this improves make help output and centralizes related logic.
If anyone feels it fits better under build, I’m happy to adjust.
Hi @loren-osborn . The "PR Title Linter" is still unhappy. "WIP" is usually for a draft PR. Is the PR ready for review? If yes, then please remove "WIP". But if you are still working on it, then please convert to draft.
Hi @loren-osborn . The "PR Title Linter" is still unhappy. "WIP" is usually for a draft PR. Is the PR ready for review? If yes, then please remove "WIP". But if you are still working on it, then please convert to draft.
Yes, while I'm close to done, it is still WIP... (I would rather mark this with a label, but I don't believe I have labeling permission)
I marked it as a draft in the GitHub UI.
You should also be able to change it; you can find a link to "Convert to draft" on an issue sidebar, and you can then click "ready for review" in the merge box when it's ready.
Thanks, @thehowl!
I believe the PR is now ready for review.
I wasn't able to find a "GitHub UI" application specifically, but I did install GitHub Desktop. From there, selecting the PR just opens it in the browser—but I did go ahead and mark it as "ready for review" from there.
Thanks again!
I think this is in a good spirit; but there's a bit too much logic being written as make rules for my taste; I don't understand what's going on in makeHelpMsgs.mk, and I don't want to.
That makes sense—thanks for the feedback!
I’ll go ahead and move the logic into a makefile_help.sh script. The only part that really needs to stay in the Makefile is the -C detection, since it doesn’t work from a subprocess.
The .mk version was meant to be simple and usable, but a shell script is clearly the better long-term fit.
Can we make a makefile_help.sh script, which given an argument of a makefile, generates the desired help output?
To match the current behavior, I’ll pass in the Makefile, the -C context, and (in the case of contribs) a list of wildcard values. The script depends a bit on the current simplicity of the Makefiles—so it may break if they ever get too clever.
@thehowl I have to head out shortly and still have quite a bit to do to get this production-ready, but I wanted to check if you’d be willing to take a quick look at misc/makefile_help.go and let me know if it’s along the lines of what you had in mind.
- I chose to implement this in Go (invoked with
go run) since I think it’ll be much more maintainable than a bash script. - It’s not yet hooked up to the Makefiles, so it’s not “live.”
- Many of the comments are outdated or incorrect—feel free to ignore them.
- I plan to refactor for clarity and add more test coverage.
- Mainly just looking to confirm whether the overall direction looks good to you.
I won’t mark this "ready for review" until it’s cleaned up—I’m just hoping to get some early feedback.
P.S. I'm available on Discord if you want to discuss this at all.
P.P.S. I’m not a huge fan of the flag package—particularly how I chose to handle list arguments with it—but it was a quick and dirty way to pass data from the Makefile without adding dependencies or doing custom parsing.
Getting close to review ready...
- Need to increase test coverage
- Need to hook Makefiles to go implementation
- Need to delete stale partial bash implementation
- Need some final testing
I'm sure there's something I forgot to fix, but I took care of all issues that I was aware of.
I computed and passed all the files and directories as arguments from make, but all the file parsing happens in Go now.
PR #4314 (chore: use 'go fmt' for core components) introduced changes that caused merge conflicts with this PR. I've resolved the conflicts in commit ad0121d.
Still hoping to get this reviewed before further changes elsewhere introduce new conflicts.
I need advice on updating this properly for PR #4292.
go -C contribs generate.% only currently applies to go -C contribs generate.gnodev. How should this be documented, and how should the no-op go -C contribs generate.%s be encoded?
@zivkovicmilos @sw360cab, would you consider the following change (or something similar) to #4338 to make it play nicely with this PR?
diff --git a/contribs/tx-archive/README.md b/contribs/tx-archive/README.md
index 7ccba96b6..ddef85a90 100644
--- a/contribs/tx-archive/README.md
+++ b/contribs/tx-archive/README.md
@@ -1,4 +1,4 @@
-<h2 align="center">⚛️ Tendermint2 Backup / Restore ⚛️</h2>
+# ⚛️ Tendermint2 Backup / Restore ⚛️
## Overview
I saw the build/test failure and took an initial look — it appears to be a crash during gnoland restart, unrelated to the changes in this PR. I’ll review it more thoroughly this evening when I’m back at my computer.
I reproduced this build failure, and am pretty confident it is unrelated to my changes. Does this fail to build on master?
Updated: Yes, I confirmed that the same failure is present upstream in master
Hey @loren-osborn, apologies about the delay. I'm taking a look now at the script. Sorry for the slow turnaround, it's been a tricky month for the project as we've undergone some big structural changes in the language
What I really want to avoid, is a list of tools in the makefile that needs to be manually updated when 1) a new tool is added or renamed or 2) a tool implements a
generatetarget. Those cases get handled automatically now.
Yep, that's also my goal. I simply think that for the maintainability of the project, we should have logic outside of makefiles.
Hopefully I answered most of your concerns directly in inline comments; tell me if there's anything else.
Cheers
we should have logic outside of makefiles.
The thing is the logic was already in the Makefile. I was just passing the result of that logic from the Makefile to the help script.
This PR is stale because it has been open 3 months with no activity. Remove stale label or comment or this will be closed in 3 months.
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "Published by a pub.dev verified publisher"){kind=small}