Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: add note to ninjia build for macOS using -jn flag #53187

Merged
merged 2 commits into from
May 30, 2024
Merged

doc: add note to ninjia build for macOS using -jn flag #53187

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f37c8a7
doc: add note to ninjia build for macOS using -jn flag
jakecastelli May 28, 2024
59e4a34
fixup!
jakecastelli May 28, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions doc/contributing/building-node-with-ninja.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,10 @@ make -j4 # With this flag, Ninja will limit itself to 4 parallel jobs,
# regardless of the number of cores on the current machine.
```

Note: if you are on macOS and use GNU Make version `3.x`, the `-jn` flag
will not work. You can either upgrade to `v4.x` (e.g. using a package manager
such as [Homebrew](https://formulae.brew.sh/formula/make#default)) or use `make JOBS=n`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If JOBS=n works for all make versions, why don’t we just change the docs to recommend it as the only solution? It’s much more straightforward than telling people to upgrade their make.

Copy link
Member Author

@jakecastelli jakecastelli May 29, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO I guess it would be better to leave people with options that they can choose? e.g. some people may have already used to the make -jn and wanna keep using it across Linux and Mac.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What's the advantage of listing both options if they do the same thing?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

make -jn is a widely used convention and shorter to type than setting JOBS. Also, if one accidentally mistyped -jn, there will almost certainly be an error, whereas mistyping the name of a variable usually doesn't even give a warning.

I don't know why Apple ships an ancient version of make by default, but it seems that upgrading it is easy enough.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I upgraded it via brew and I still got the error. Switching to the variable worked for me. Presumably the upgrade didn't put the new version in my path or something but I didn't dig into it.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So essentially the instructions are:

Use JOBS=N; or if you’re on macOS and you want to type -jN instead, use Homebrew to upgrade make and add $HOMEBREW_PREFIX/opt/make/libexec/gnubin to your $PATH

The second option is so complex that I don’t really see the point in mentioning it?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Honestly it's up to Apple to provide their users with a version of make that isn't old enough to vote in most countries.

As long as they don't, we can — and probably should — give users both options. Clearly, there is an expectation among contributors that -jn should work, and it can.

If you think the details of upgrading to a version of make from the last decade are too complex/verbose, we can probably omit those and just say "please upgrade to version 4 of GNU make" as option two.

In any case, if probably doesn't hurt to make does not work a hyperlink to the issue that Yagiz created so that readers can find plenty of context there.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I also don’t understand how this broke. I’ve used -j8 for years on Mac and it was only recently that it started erroring for me, and fortunately I happened to find this PR. So I’m all for updating the instructions, but did we change something recently that requires a newer make? If so, is this the only thing that’s broken in the old make or should we do some kind of check that users are running make 4+?

If using the old make is okay, I would update all the places we currently mention -jN to instead be JOBS=N and then add a note like “If you are using a current version of make, which is likely for most Linux OSes but currently not for macOS, you can replace JOBS=N with -jN.” As in, we should default to the instruction that should work for everyone.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW I installed an up-to-date version using Nix, I had to restart my shell and it worked fine. I'm -1 on Goeffrey's proposal, I agree with Tobias it's up to the user to use an up-to-date version of make. If it's upgrading is too complicated, not passing -j is also an option – and you'd get the same behavior as before – and also building with ninja is not the default.

Copy link
Member Author

@jakecastelli jakecastelli May 30, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I also don’t understand how this broke. I’ve used -j8 for years on Mac and it was only recently that it started erroring for me

The sad story is that -jn may never have truly worked. see #53176 (comment),
#53176 (comment),
#53176 (comment).

(the tldr is that I have tested on the previous "working" version and found the -jn was not being propagated)


## Producing a debug build

To create a debug build rather than a release build:
Expand Down