Skip to content

doc: add guide on maintaining the build files #16975

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

Closed
joyeecheung wants to merge 2 commits into from
Closed

doc: add guide on maintaining the build files #16975

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f9fec80
build: document targets in the Makefile
joyeecheung Nov 12, 2017
fef681b
doc: add guide on maintaining build files
joyeecheung Nov 12, 2017
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
Prev Previous commit
doc: add guide on maintaining build files
  • Loading branch information
@joyeecheung
joyeecheung committed Jan 6, 2018
commit fef681bb4c0f429a210b02df7a2eb339c0f102dc
52 changes: 52 additions & 0 deletions doc/guides/maintaining-the-build-files.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# Maintaining the Build files

This document explains how to maintain the build files in the codebase.

## Overview

On how to build the Node.js core, see [Building Node.js](../../BUILDING.md).

There are three main build files that may be directly run when building Node.js:

- `configure`: A Python 2 script that detects system capabilities and runs
[GYP][]. It generates `config.gypi` which includes parameters used by GYP to
Copy link
Copy Markdown
Member

@gibfahn gibfahn Jan 3, 2018

Choose a reason for hiding this comment

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

Missing link

Copy link
Copy Markdown
Member Author

@joyeecheung joyeecheung Jan 3, 2018

Choose a reason for hiding this comment

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

Ooops, deleted by accident, thanks for catching that.

create platform-dependent build files. Its output is usually in one of these
formats: Makefile, MSbuild, ninja, or XCode project files. (Note: the main
Makefile mentioned below is maintained separately by humans). For a detailed
guide on this script, see [configure](#configure).
- `vcbuild.bat`: A Windows Batch Script that locates build tools, provides a
subset of the targets avilable in the [Makefile](#makefile), and a few targets
of its own. For a detailed guide on this script, see
[vcbuild.bat](#vcbuild.bat).
- `Makefile`: A Makefile that can be run with GNU Make. It provides a set of
targets that build and test the Node.js binary, produce releases and
documentation, and interact with the CI to run benchmarks or tests. For a
detailed guide on this file, see [Makefile](#makefile).

On Windows `vcbuild.bat` runs [configure](#configure) before building the
Node.js binary, on other systems `configure` must be run manually before running
`make` on the `Makefile`.

## vcbuild.bat

To see the help text, run `.\vcbuild help`. Update this file when you need to
update the build and testing process on Windows.

## configure

To see the help text, run `python configure --help`. Update this file when you
need to update the configuration process.

## Makefile
Copy link
Copy Markdown
Member

@gibfahn gibfahn Nov 15, 2017

Choose a reason for hiding this comment

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

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


To see the help text, run `make help`. This file is not generated, it is
maintained by humans. Note that this is not usually run on Windows, where
[vcbuild.bat](#vcbuild.bat) is used instead.

### Options

- `-j <n>`: number of threads used to build the binary. Note that on the non-ci
targets, the parallel tests will take up all the available cores, regardless
of this option.

[GYP]: https://gyp.gsrc.io/docs/UserDocumentation.md