Closed Bug 749314 Opened 10 years ago Closed 9 years ago
Add a 'help' target
I can never remember the various targets for running tests. It would be nice to have some minimal documentation in the build system itself.
Attachment #618767 - Flags: feedback?(khuey)
\o/ Perhaps morph into 'make help' ?
I'm of the mind to want this WONTFIXED The initial goal of this is to duplicate in build-system a *new* arbitrary target that is hard to discover a way to identify *old* arbitrary targets that are hard to discover, while systemically documenting other targets that are otherwise a "huh" and not-needed for many users. The initial goals of this documentation is also served at https://developer.mozilla.org/en/Mozilla_automated_testing
I don't understand what you're trying to do here. I think you'd be better off just adding comments to the relevant stuff.
It's all about usability. I'm willing to bet a lot of newcomers to the build system type things like `make test` in hopes it "does the right thing." Having simple stubs to point people in the right direction would be much more helpful than "make: *** No rule to make target `test'. Stop."
Ok. If you want to add a test target that lists the different type of tests we have and how to run them, I'll r+ that. I don't see what adding another obscure target is going to do to help though.
(In reply to Justin Wood (:Callek) from comment #3) > I'm of the mind to want this WONTFIXED > > The initial goal of this is to duplicate in build-system a *new* arbitrary > target that is hard to discover a way to identify *old* arbitrary targets > that are hard to discover, while systemically documenting other targets that > are otherwise a "huh" and not-needed for many users. Perhaps. (And maybe 'make help' rather than 'make list-targets' would be a better name.) But it's a single target, and imho it serves a common enough need that people could remember it. And I shouldn't have documented eg tools. That was most a test to see how it would work to have stuff scattered around. > The initial goals of this documentation is also served at > https://developer.mozilla.org/en/Mozilla_automated_testing Except that I always have to find that page, generally via a Google search, and wade through it. I'd prefer something that I already definitely have, and that gives very brief usage descriptions. A link to that page would probably be appropriate. (In reply to Kyle Huey [:khuey] (firstname.lastname@example.org) from comment #4) > I don't understand what you're trying to do here. I think you'd be better > off just adding comments to the relevant stuff. I can't *find* the relevant stuff! I can't count the number of times I've done a full-tree grep of 'check-single', 'test-one-file', etc.
(In reply to Steve Fink [:sfink] from comment #7) > > The initial goals of this documentation is also served at > > https://developer.mozilla.org/en/Mozilla_automated_testing > > Except that I always have to find that page, generally via a Google search, > and wade through it. I'd prefer something that I already definitely have, > and that gives very brief usage descriptions. +1 > A link to that page would probably be appropriate. Even if you have a link to the page in there, it's annoying to have the documentation for basic stuff (and even not-so-basic stuff!) not in the source code, right alongside whatever it is you're trying to do.
Oh, and I did kind of want to keep eg the documentation for 'make clean', since it's pretty common for people to think it works like most build systems'. Though without the snark, of course. There's a discoverability problem, I admit, so perhaps it should be displayed also or instead at the end of 'make clean' output. I'd love to have some documentation included for eg the magic directories (like toolkit/library) and what you should use for cases that aren't handled as well by the dependency system (I'm not sure about this, but it seems like changing IDL files requires a top-level rebuild where changing their neighboring C++ files doesn't.) But it'd be easy to go too far and make something that nobody would bother reading through. I guess we could start with adding help:
Summary: Add a 'list-targets' target → Add a 'help' target
hint: don't hit <tab> <enter> when entering a comment. help: @echo "See http://wiki/how_to_use_the_mozilla_build_system"
and then patch in whatever else we want, I mean.
At some point, we might consider replacing/supplementing client.mk with something not automake. IMO it is easier to manage these things in a higher-level language (like Python). And, having a higher-level language (like Python) as the driver for the build system opens up a whole host of other possibilities. This is the direction I started with Build Splendid (https://github.com/indygreg/mozilla-central/blob/build-splendid/README.txt). IMO the cli driver (https://github.com/indygreg/mozilla-central/blob/build-splendid/build/buildsplendid/cli.py) is much easier to work with than makefiles. Just getting proper argument parsing and a logging framework is worth the transition, IMO. If/when I start to land my build system changes, the first bit will likely be the user-friendly ./build.py driver for the build system.
client.mk is not automake.
Comment on attachment 618767 [details] [diff] [review] Add a 'list-targets' target Review of attachment 618767 [details] [diff] [review]: ----------------------------------------------------------------- I think we discussed on IRC that more hard to discover targets is not that helpful.
Attachment #618767 - Flags: feedback?(khuey) → feedback-
I'm going to assume that gps's push to rip all of the funky targets out of the makefiles is going to obviate the need for this.
Status: NEW → RESOLVED
Closed: 9 years ago
Resolution: --- → WONTFIX
The targets may remain for a while. But, I think mach (bug 751795) will provide all the user-friendly bits, including "help."
You need to log in before you can comment on or make changes to this bug.