I am not sure if pasting the help text here is useful..although it does give you an idea about what it does if you don't know what it is.

I think the above paragraph is enough. Including the text here will only drift from the actual help text over time.

Agreed with @richardlau , don't think we should duplicate the ./configure --help output.

We should document the similarity/differences between vcbuild.bat and Makefile, though not necessarily in this PR (I am not familiar enough with vcbuild.bat to be comfortable to write a guide on it anyway)

that'd be quite a job for someone! one of it's biggest problems is that it lacks most of the smarts that make brings to the table and we only do a partial job of emulating the bits that are needed

Uh, wait, I don't think this is true..? From what I can tell node-test-binary-arm only runs test-ci-js, But then I am not sure who uses this target (test-ci-native) and how are the addons tested on the pis @nodejs/build

node-test-binary-arm:

case $RUN_SUBSET in
  addons)
    PYTHON=python FLAKY_TESTS=$FLAKY_TESTS_MODE make test-ci-native
    ;;
  *)
    export CC=should-not-compile CXX=should-not-compile # Prevent building
    PYTHON=python FLAKY_TESTS=$FLAKY_TESTS_MODE TEST_CI_ARGS="--run=${RUN_SUBSET},7" make test-ci-js
    ;;
esac

i.e. it's used for the addons tests on arm-fanned.

Parallel tests are run in parallel by default (by virtue of -J specified to the test runner in Makefile), even if the make command is -j1.

There's an awkward catch to this that's not documented anywhere that probably should be since I'm finding Jenkins jobs that don't do this properly: a lot of the -ci targets use this PARALLEL_ARGS variable to insert -j X for tools/test.py (-J isn't used in any of the -ci targets). Unfortunately this variable is only set if $JOBS exists, and this isn't automatically set just because you supply -j X to make. In fact, it's kind of difficult to determine the -j argument inside a Makefile in a cross-platform way (but we should probably try, there's an interesting stackoverflow suggestion here). So you have to give JOBS=X when running the -ci targets.

-J is done automatically for tests on non-ci targets so it takes up "as many cores as you have" for tests as @TimothyGu said.

@TimothyGu @rvagg Thanks for the correction, I'll add a note in the Makefile about this, and change this part to just "number of threads used to build the binary"

Typo maintained.

Maybe reword this, e.g. and is maintained to avoid being misread as is not (generated and maintained).

+1, I totally misread this 😁

macOS

This comment doesn't really convey any additional information than can be inferred from the target name.

I think clean is a standard enough makefile target name that this comment shouldn't be necessary. If it is kept, suggest Remove the artifacts... reword.

This is mostly to distinguish clean from docclean, distclean, test-addons-clean and friends.

Maybe a note that this target will fail unless NODE_VERSION_IS_RELEASE is #define'd as 1 in src/node_version.h.

@richardlau good catch, though I think this should be documented in the makefile instead.

Would a maintainer need to know that? Seems more relevant for users.

available

maybe use backticks for `make coverage-test`. I read this wrong on first parse and thought it was just awkward wording

I think rpi is the only exception, I've just been grepping through jenkins config files and it's the only one I can find.

now that I've seen this and noticed CONFIG_FLAGS I've gone and edited node-test-commit-linux-fips to not be an exception here, it now does

PYTHON=python FLAKY_TESTS=$FLAKY_TESTS_MODE CONFIG_FLAGS=--openssl-fips=$WORKSPACE/fipscanisterdir $MAKE run-ci -j $JOBS

so it's using run-ci like the rest. I'll do the same for the new jobs I'm building out in node-test-commit-linux-linked that do a similar ./configure override thing.

So the only thing I'd suggest about this option is that you note that it's called by run-ci, we don't actually call it directly anywhere.

_(FYI I also think that node-test-commit-linux-fips wasn't running tests in parallel due to a mis-application of JOBS and -j and I think that should be fixed now, that would explain why it's been taking more time than it should in some instances).

fips isn't an exception here, although it does run test-ci directly a second time with FIPS enabled

coverage is another exception that doesn't run this

you could note that these -upload tasks are strictly for release builds on release machines only, unless you think that's obvious

space needed before (unix-like)

this should probably be python configure --help

also worth listing:

BUILDTYPE
JOBS
CONFIG_FLAGS
BUILD_DOWNLOAD_FLAGS
BUILD_INTL_FLAGS

#vcbuild.bat -> #vcbuildbat ?

configures and prepares?

A nit: most of the explanations start with a lower case word, some with an upper case one: Build, Generate, Generate, Enable etc.

I think these come direct from the configure help, so any changes should be made there.

@richardlau Yes.

@vsemozhetbyt Do you want to open a PR to fix the configure script? Or I can do that as well.

Though these are rather simple fixes, I would rather abstain as I know neither Python nor the format of this file. Sorry(

profileJavaScript -> profile JavaScript ?
nodejs -> Node.js ?

#17094

nodejs -> Node.js ?

avilable -> available

benchamarks -> benchmarks

OpenSSl -> OpenSSL

docuement -> document

triggered -> be triggered

Remove the and which

If we're going to say this here, is it worth saying something similar for make all?

binary -> binaries

Can be run manually too.

Hmm I think it's obvious without saying that all the targets here can be run manually (some needs certain environment variables and some probably shouldn't be run manually though)

I would agree, but if you say:

# Note that this is for developers, it is not run on the CI. See run-ci.

elsewhere, then this line suggests that it's used exclusively by the CI job.

Agreed with @richardlau , don't think we should duplicate the ./configure --help output.

+1, I totally misread this 😁

I was compiling Alacritty the other day, and I noticed that their make actually defaults to showing help (alias for make help) rather than doing anything. It actually looks really nice, and it'd be really useful if we could do something similar.

I think a help option to make would be less likely to bitrot than separate documentation.

https://github.com/jwilm/alacritty/blob/245a80078180acc2a0a1addc569c15b77991c1c3/Makefile#L18-L21

I think you can just say python configure for both Unix and Windows.

typo: on?