hacker news discussion -> manual updates

[Evan Martin]

We were on Hacker News again:
http://news.ycombinator.com/item?id=3895551

Whenever Ninja comes up on a site like HN or reddit, the same
questions and misunderstandings come up. I blame myself for not being
clear enough in the documentation.
Similarly so for the person on this list who was asking how to use
wildcards in build files.

With a night to think about it I think I finally came up with the
right metaphor: "Where other build systems are high-level languages
Ninja aims to be an assembler."

I've updated the home page to try to get to the point more quickly:
http://martine.github.com/ninja/
and I've rearranged the manual to emphasize that you should be using
gyp or CMake:
http://martine.github.com/ninja/manual.html
(what's new: deleted text from the intro, "philosophical overview",
the whole "using ninja for your project" section).

I'm always a little uncomfortable with how much "ninja is awesome"
text I should include versus modesty.
If you have feedback on the above, I'd appreciate it.

I'm especially not clear on whether build timings belong in the
manual, but I had hoped by including some it would help illustrate
which projects Ninja helps on.

[Nico Weber]

On Fri, Apr 27, 2012 at 9:28 AM, Evan Martin <mar...@danga.com> wrote:
> We were on Hacker News again:
> http://news.ycombinator.com/item?id=3895551
>
> Whenever Ninja comes up on a site like HN or reddit, the same
> questions and misunderstandings come up.  I blame myself for not being
> clear enough in the documentation.
> Similarly so for the person on this list who was asking how to use
> wildcards in build files.
>
> With a night to think about it I think I finally came up with the
> right metaphor: "Where other build systems are high-level languages
> Ninja aims to be an assembler."
>
> I've updated the home page to try to get to the point more quickly:
>  http://martine.github.com/ninja/
> and I've rearranged the manual to emphasize that you should be using
> gyp or CMake:
>  http://martine.github.com/ninja/manual.html
> (what's new: deleted text from the intro, "philosophical overview",
> the whole "using ninja for your project" section).

I like it. (But I liked the old one too). I think "$:" is missing from
the manual.

> I'm always a little uncomfortable with how much "ninja is awesome"
> text I should include versus modesty.
> If you have feedback on the above, I'd appreciate it.

It probably depends on which audience you want to reach. I think the
current manual does a good job of informing dedicated build engineers
of bigger projects what ninja's tradeoffs are. If you want a bigger
audience than that, providing binaries and a stable version probably
helps more than wordsmithing the manual anyways (building programs
from source is fairly unusual for the non-linux world) :-)

> I'm especially not clear on whether build timings belong in the
> manual, but I had hoped by including some it would help illustrate
> which projects Ninja helps on.

Nico

[tychoish]

On Fri, Apr 27, 2012 at 09:28:07AM -0700, Evan Martin wrote:
> We were on Hacker News again:
> http://news.ycombinator.com/item?id=3895551
>
> Whenever Ninja comes up on a site like HN or reddit, the same
> questions and misunderstandings come up. I blame myself for not being
> clear enough in the documentation.

This is probably a fair assessment. While some of this is unavoidable
(people don't tend to read documentation until they have a specific
problem, no matter how much energy you put into it,) I think it's a
reasonable goal for documentation to answer most *common* questions,
particularly if they come up again and again.

> I'm always a little uncomfortable with how much "ninja is awesome"
> text I should include versus modesty. If you have feedback on the
> above, I'd appreciate it.

When I started this reply, I thought "there's nothing really wrong with
a project showing a little bit of self confidence," but as I think about
it more, I think bragging v. modesty, obscures the real issue. The thing
that would be really helpful would be to have a more clear understanding
of the particular situations where ninja makes a lot of sense, and the
situations where ninja *doesn't* wouldn't be the right build tool for
the job.

Additionally, it might be nice to have a few examples/tutorials that
provide an overview of using ninja in concert with
gyp/cmake/ninja_script.py. If ninja really is an assembler, the
documentation ought to (I think,) document the use of ninja in concert
with gyp/cmake/etc, or at least provide examples. I'm not sure that this
kind of information includes inline in the current manual, and I'm
willing to do a little work to build these tutorials/documents, if
there's an interest in this. Pull request and an additional document in
the docs/ folder make the most sense or is there another
format/forum for this kind of resource?

Does anyone have a public/open source project that uses gyp other than
Chromium that might provide a good example?

> I'm especially not clear on whether build timings belong in the
> manual, but I had hoped by including some it would help illustrate
> which projects Ninja helps on.

I think build timings are perfectly acceptable for inclusion.

--
tycho(ish) @
ga...@tychoish.com
http://tychoish.com/
"don't get it right, get it written" -- james thurber

[Evan Martin]

On Sun, Apr 29, 2012 at 6:32 PM, tychoish <ga...@tychoish.com> wrote:
>> I'm always a little uncomfortable with how much "ninja is awesome"
>> text I should include versus modesty. If you have feedback on the
>> above, I'd appreciate it.
>
> When I started this reply, I thought "there's nothing really wrong with
> a project showing a little bit of self confidence," but as I think about
> it more, I think bragging v. modesty, obscures the real issue. The thing
> that would be really helpful would be to have a more clear understanding
> of the particular situations where ninja makes a lot of sense, and the
> situations where ninja *doesn't* wouldn't be the right build tool for
> the job.

Yes, this is exactly my hesitation. I vacillate between "you should
always use a more popular system like scons or waf until speed is a
concern" but then think there are plenty of people who just want a
better Make and how we provide that more than anyone.

I'll revisit it again sometime.

> Additionally, it might be nice to have a few examples/tutorials that
> provide an overview of using ninja in concert with
> gyp/cmake/ninja_script.py. If ninja really is an assembler, the
> documentation ought to (I think,) document the use of ninja in concert
> with gyp/cmake/etc, or at least provide examples. I'm not sure that this
> kind of information includes inline in the current manual, and I'm
> willing to do a little work to build these tutorials/documents, if
> there's an interest in this. Pull request and an additional document in
> the docs/ folder make the most sense or is there another
> format/forum for this kind of resource?

I've considered splitting the manual into "how to use ninja from the
perspective of someone who doesn't want to write a build system"
(which would include command-line flags and your above description)
and then a separate "how to write ninja inputs" (which would include
all the syntax etc.) but the two end up overlapping a bit and there
are too much docs already. :)

> Does anyone have a public/open source project that uses gyp other than
> Chromium that might provide a good example?

I don't think there are any. :)

Node.js uses gyp (because v8 does), but I think they currently rely on
features specific to gyp's Makefile output. I bet it wouldn't be too
hard to make work under Ninja but I also wonder if it would benefit
them too much.

[sam kleinman]

On Mon, Apr 30, 2012 at 12:25:30AM -0700, Evan Martin wrote:

> I've considered splitting the manual into "how to use ninja from the
> perspective of someone who doesn't want to write a build system"
> (which would include command-line flags and your above description)
> and then a separate "how to write ninja inputs" (which would include
> all the syntax etc.) but the two end up overlapping a bit and there
> are too much docs already. :)

No such thing. Or at least, no such thing as long as the docs are in
state where they make use/understanding/difficult.

Would it make sense to turn the current docs into three parts (files?):

- Reference: short descriptions of all of the nobs and buttons and their
behavior.

- The bulk of the current documentation ("how to use ninja from the
perspective of someone who wants to write a build system.")

- Documents to support people who want to use ninja, how to write ninja
inputs, preliminary/high-level documentation of using ninja/gyp/etc.

> > Does anyone have a public/open source project that uses gyp other than
> > Chromium that might provide a good example?
>
> I don't think there are any. :)

Well blast!

> Node.js uses gyp (because v8 does), but I think they currently rely on
> features specific to gyp's Makefile output. I bet it wouldn't be too
> hard to make work under Ninja but I also wonder if it would benefit
> them too much.

Would working toward getting node into a place where it uses gyp in a
make/ninja compatible way, be incredibly difficult? And useful as
another test bed? For ninja and/or gyp?

Cheers,
sam

--
Sam Kleinman (tychoish):
- ga...@tychoish.com
- tychoish <http://tychoish.com/>