mirror of
https://github.com/nodejs/node.git
synced 2024-11-21 10:59:27 +00:00
doc: update markdown formatting for *.md files
Fix formatting that will change when run through upcoming remark preset. PR-URL: https://github.com/nodejs/node/pull/40154 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Michael Dawson <midawson@redhat.com>
This commit is contained in:
Rich Trott
Node.js GitHub Bot
parent
d05cca94ea
commit
549f96889a
69
BUILDING.md
69
BUILDING.md
@ -120,31 +120,31 @@ platforms. This is true regardless of entries in the table below.
|
||||
| FreeBSD | x64 | >= 11 | Experimental | Downgraded as of Node.js 12 <sup>[7](#fn7)</sup> |
|
||||
|
||||
<em id="fn1">1</em>: GCC 8 is not provided on the base platform. Users will
|
||||
need the
|
||||
[Toolchain test builds PPA](https://launchpad.net/~ubuntu-toolchain-r/+archive/ubuntu/test?field.series_filter=xenial)
|
||||
or similar to source a newer compiler.
|
||||
need the
|
||||
[Toolchain test builds PPA](https://launchpad.net/~ubuntu-toolchain-r/+archive/ubuntu/test?field.series_filter=xenial)
|
||||
or similar to source a newer compiler.
|
||||
|
||||
<em id="fn2">2</em>: GCC 8 is not provided on the base platform. Users will
|
||||
need the
|
||||
[devtoolset-8](https://www.softwarecollections.org/en/scls/rhscl/devtoolset-8/)
|
||||
or later to source a newer compiler.
|
||||
need the
|
||||
[devtoolset-8](https://www.softwarecollections.org/en/scls/rhscl/devtoolset-8/)
|
||||
or later to source a newer compiler.
|
||||
|
||||
<em id="fn3">3</em>: Older kernel versions may work for ARM64. However the
|
||||
Node.js test infrastructure only tests >= 4.5.
|
||||
Node.js test infrastructure only tests >= 4.5.
|
||||
|
||||
<em id="fn4">4</em>: On Windows, running Node.js in Windows terminal emulators
|
||||
like `mintty` requires the usage of [winpty](https://github.com/rprichard/winpty)
|
||||
for the tty channels to work (e.g. `winpty node.exe script.js`).
|
||||
In "Git bash" if you call the node shell alias (`node` without the `.exe`
|
||||
extension), `winpty` is used automatically.
|
||||
like `mintty` requires the usage of [winpty](https://github.com/rprichard/winpty)
|
||||
for the tty channels to work (e.g. `winpty node.exe script.js`).
|
||||
In "Git bash" if you call the node shell alias (`node` without the `.exe`
|
||||
extension), `winpty` is used automatically.
|
||||
|
||||
<em id="fn5">5</em>: The Windows Subsystem for Linux (WSL) is not
|
||||
supported, but the GNU/Linux build process and binaries should work. The
|
||||
community will only address issues that reproduce on native GNU/Linux
|
||||
systems. Issues that only reproduce on WSL should be reported in the
|
||||
[WSL issue tracker](https://github.com/Microsoft/WSL/issues). Running the
|
||||
Windows binary (`node.exe`) in WSL is not recommended. It will not work
|
||||
without workarounds such as stdio redirection.
|
||||
supported, but the GNU/Linux build process and binaries should work. The
|
||||
community will only address issues that reproduce on native GNU/Linux
|
||||
systems. Issues that only reproduce on WSL should be reported in the
|
||||
[WSL issue tracker](https://github.com/Microsoft/WSL/issues). Running the
|
||||
Windows binary (`node.exe`) in WSL is not recommended. It will not work
|
||||
without workarounds such as stdio redirection.
|
||||
|
||||
<em id="fn6">6</em>: Running Node.js on x86 Windows should work and binaries
|
||||
are provided. However, tests in our infrastructure only run on WoW64.
|
||||
@ -195,7 +195,7 @@ Ubuntu 14.04 and Debian 8.
|
||||
#### OpenSSL asm support
|
||||
|
||||
OpenSSL-1.1.1 requires the following assembler version for use of asm
|
||||
support on x86_64 and ia32.
|
||||
support on x86\_64 and ia32.
|
||||
|
||||
For use of AVX-512,
|
||||
|
||||
@ -212,9 +212,9 @@ For use of AVX2,
|
||||
* nasm version 2.10 or higher in Windows
|
||||
|
||||
Please refer to
|
||||
<https://www.openssl.org/docs/man1.1.1/man3/OPENSSL_ia32cap.html> for details.
|
||||
<https://www.openssl.org/docs/man1.1.1/man3/OPENSSL_ia32cap.html> for details.
|
||||
|
||||
If compiling without one of the above, use `configure` with the
|
||||
If compiling without one of the above, use `configure` with the
|
||||
`--openssl-no-asm` flag. Otherwise, `configure` will fail.
|
||||
|
||||
### Previous versions of this document
|
||||
@ -232,6 +232,7 @@ Consult previous versions of this document for older versions of Node.js:
|
||||
### Note about Python
|
||||
|
||||
The Node.js project supports Python >= 3 for building and testing.
|
||||
|
||||
### Unix and macOS
|
||||
|
||||
#### Unix prerequisites
|
||||
@ -480,7 +481,7 @@ release version is actually installed when you run `make install`.
|
||||
To use the debug build with all the normal dependencies overwrite the release
|
||||
version in the install directory:
|
||||
|
||||
``` console
|
||||
```console
|
||||
$ make install PREFIX=/opt/node-debug/
|
||||
$ cp -a -f out/Debug/node /opt/node-debug/node
|
||||
```
|
||||
@ -496,7 +497,7 @@ was captured on (i.e. 64-bit `gdb` for `node` built on a 64-bit system, Linux
|
||||
|
||||
Example of generating a backtrace from the core dump:
|
||||
|
||||
``` console
|
||||
```console
|
||||
$ gdb /opt/node-debug/node core.node.8.1535359906
|
||||
$ backtrace
|
||||
```
|
||||
@ -507,12 +508,12 @@ $ backtrace
|
||||
related bugs. ASAN builds are currently only supported on linux.
|
||||
If you want to check it on Windows or macOS or you want a consistent toolchain
|
||||
on Linux, you can try [Docker](https://www.docker.com/products/docker-desktop)
|
||||
(using an image like `gengjiawen/node-build:2020-02-14`).
|
||||
(using an image like `gengjiawen/node-build:2020-02-14`).
|
||||
|
||||
The `--debug` is not necessary and will slow down build and testing, but it can
|
||||
show clear stacktrace if ASAN hits an issue.
|
||||
|
||||
``` console
|
||||
```console
|
||||
$ ./configure --debug --enable-asan && make -j4
|
||||
$ make test-only
|
||||
```
|
||||
@ -521,6 +522,7 @@ $ make test-only
|
||||
|
||||
If you plan to frequently rebuild Node.js, especially if using several branches,
|
||||
installing `ccache` can help to greatly reduce build times. Set up with:
|
||||
|
||||
```console
|
||||
$ sudo apt install ccache # for Debian/Ubuntu, included in most Linux distros
|
||||
$ ccache -o cache_dir=<tmp_dir>
|
||||
@ -528,13 +530,16 @@ $ ccache -o max_size=5.0G
|
||||
$ export CC="ccache gcc" # add to your .profile
|
||||
$ export CXX="ccache g++" # add to your .profile
|
||||
```
|
||||
|
||||
This will allow for near-instantaneous rebuilds even when switching branches.
|
||||
|
||||
When modifying only the JS layer in `lib`, it is possible to externally load it
|
||||
without modifying the executable:
|
||||
|
||||
```console
|
||||
$ ./configure --node-builtin-modules-path $(pwd)
|
||||
```
|
||||
|
||||
The resulting binary won't include any JS files and will try to load them from
|
||||
the specified directory. The JS debugger of Visual Studio Code supports this
|
||||
configuration since the November 2020 version and allows for setting
|
||||
@ -678,7 +683,7 @@ $ ./configure --with-intl=full-icu
|
||||
|
||||
### Trimmed: `small-icu` (English only) support
|
||||
|
||||
In this configuration, only English data is included, but
|
||||
In this configuration, only English data is included, but
|
||||
the full `Intl` (ECMA-402) APIs. It does not need to download
|
||||
any dependencies to function. You can add full data at runtime.
|
||||
|
||||
@ -774,6 +779,7 @@ If you want to build Node.js using openssl-3.0.0+quic, you can follow these
|
||||
steps:
|
||||
|
||||
**clone OpenSSL source and prepare build**
|
||||
|
||||
```bash
|
||||
git clone git@github.com:quictls/openssl.git
|
||||
|
||||
@ -791,6 +797,7 @@ will publish the OpenSSL libraries and such. We will also use this path
|
||||
(and sub-paths) later when compiling Node.js.
|
||||
|
||||
**compile and install OpenSSL**
|
||||
|
||||
```console
|
||||
make -j8
|
||||
make install
|
||||
@ -806,6 +813,7 @@ find the `fipsmodule.cnf` file - let's add the following to the end of the
|
||||
`openssl.cnf` file.
|
||||
|
||||
**alter openssl.cnf**
|
||||
|
||||
```text
|
||||
.include fipsmodule.cnf
|
||||
|
||||
@ -826,6 +834,7 @@ sure that you specify an absolute path for the `.include fipsmodule.cnf` line -
|
||||
using relative paths did not work on my system!
|
||||
|
||||
**alter openssl.cnf using a script**
|
||||
|
||||
```console
|
||||
cat <<EOT >> /path/to/install/dir/ssl/openssl.cnf
|
||||
.include /path/to/install/dir/ssl/fipsmodule.cnf
|
||||
@ -845,12 +854,14 @@ EOT
|
||||
As you might have picked a non-custom path for your OpenSSL install dir, we
|
||||
have to export the following two environment variables in order for Node.js to
|
||||
find our OpenSSL modules we built beforehand:
|
||||
|
||||
```console
|
||||
export OPENSSL_CONF=/path/to/install/dir/ssl/openssl.cnf
|
||||
export OPENSSL_MODULES=/path/to/install/dir/lib/ossl-modules
|
||||
```
|
||||
|
||||
**build Node.js**
|
||||
|
||||
```console
|
||||
./configure \
|
||||
--shared-openssl \
|
||||
@ -865,6 +876,7 @@ make -j8
|
||||
```
|
||||
|
||||
**verify the produced executable**
|
||||
|
||||
```console
|
||||
ldd ./node
|
||||
linux-vdso.so.1 (0x00007ffd7917b000)
|
||||
@ -884,12 +896,14 @@ If the `ldd` command says that `libcrypto` cannot be found one needs to set
|
||||
`--shared-openssl-libpath` (see previous step).
|
||||
|
||||
**verify the OpenSSL version**
|
||||
|
||||
```console
|
||||
./node -p process.versions.openssl
|
||||
3.0.0-alpha16+quic
|
||||
```
|
||||
|
||||
**verify that FIPS is available**
|
||||
|
||||
```console
|
||||
./node -p 'process.config.variables.openssl_is_fips'
|
||||
true
|
||||
@ -905,13 +919,16 @@ executable. See sections
|
||||
[Enabling FIPS using OpenSSL config](#enabling-fips-using-openssl-config) below.
|
||||
|
||||
### Enabling FIPS using Node.js options
|
||||
|
||||
This is done using one of the Node.js options `--enable-fips` or
|
||||
`--force-fips`, for example:
|
||||
|
||||
```console
|
||||
$ node --enable-fips -p 'crypto.getFips()'
|
||||
```
|
||||
|
||||
### Enabling FIPS using OpenSSL config
|
||||
|
||||
This example show that using OpenSSL's configuration file, FIPS can be enabled
|
||||
without specifying the `--enable-fips` or `--force-fips` options by setting
|
||||
`default_properties = fips=yes` in the FIPS configuration file. See
|
||||
@ -920,6 +937,7 @@ for details.
|
||||
|
||||
For this to work the OpenSSL configuration file (default openssl.cnf) needs to
|
||||
be updated. The following shows an example:
|
||||
|
||||
```console
|
||||
openssl_conf = openssl_init
|
||||
|
||||
@ -939,6 +957,7 @@ activate = 1
|
||||
[algorithm_sect]
|
||||
default_properties = fips=yes
|
||||
```
|
||||
|
||||
After this change Node.js can be run without the `--enable-fips` or `--force-fips`
|
||||
options.
|
||||
|
||||
|
||||
@ -24,6 +24,7 @@ Please use the following table to find the changelog for a specific Node.js
|
||||
release.
|
||||
|
||||
<!--lint disable maximum-line-length-->
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th title="Current"><a href="doc/changelogs/CHANGELOG_V16.md">16</a><sup>Current</sup></th>
|
||||
@ -138,8 +139,9 @@ release.
|
||||
LTS releases.
|
||||
* Release versions in **bold** text are the most recent supported releases.
|
||||
|
||||
----
|
||||
----
|
||||
***
|
||||
|
||||
***
|
||||
|
||||
## 2016-05-06, Version 0.12.14 (Maintenance), @rvagg
|
||||
|
||||
@ -1355,7 +1357,7 @@ release.
|
||||
|
||||
## 2009.08.21, Version 0.1.5
|
||||
|
||||
<a href="doc/changelogs/CHANGELOG_ARCHIVE.md#0.1.5>Moved to doc/changelogs/CHANGELOG_V6.md#6.0.0</a>.
|
||||
<a href="doc/changelogs/CHANGELOG_ARCHIVE.md#0.1.5">Moved to doc/changelogs/CHANGELOG_V6.md#6.0.0</a>.
|
||||
|
||||
## 2009.08.13, Version 0.1.4
|
||||
|
||||
|
||||
@ -29,8 +29,10 @@ See [details on our policy on Code of Conduct](./doc/guides/contributing/code-of
|
||||
* [Notes](./doc/guides/contributing/pull-requests.md#notes)
|
||||
|
||||
<a id="developers-certificate-of-origin"></a>
|
||||
|
||||
## Developer's Certificate of Origin 1.1
|
||||
|
||||
<pre>
|
||||
By making a contribution to this project, I certify that:
|
||||
|
||||
(a) The contribution was created in whole or in part by me and I
|
||||
@ -54,3 +56,4 @@ By making a contribution to this project, I certify that:
|
||||
personal information I submit with it, including my sign-off) is
|
||||
maintained indefinitely and may be redistributed consistent with
|
||||
this project or the open source license(s) involved.
|
||||
</pre>
|
||||
|
||||
@ -153,8 +153,8 @@ the nomination fails.
|
||||
|
||||
There are steps a nominator can take in advance to make a nomination as
|
||||
frictionless as possible. To request feedback from other collaborators in
|
||||
private, use the [collaborators discussion page][]
|
||||
(which only collaborators may view). A nominator may also work with the
|
||||
private, use the [collaborators discussion page][]
|
||||
(which only collaborators may view). A nominator may also work with the
|
||||
nominee to improve their contribution profile.
|
||||
|
||||
Collaborators might overlook someone with valuable contributions. In that case,
|
||||
|
||||
@ -51,12 +51,13 @@ onboarding session.
|
||||
[Publicizing or hiding organization membership][].
|
||||
|
||||
* Notifications:
|
||||
* Use [https://github.com/notifications](https://github.com/notifications) or
|
||||
* Use <https://github.com/notifications> or
|
||||
set up email
|
||||
* Watching the main repository will flood your inbox (several hundred
|
||||
notifications on typical weekdays), so be prepared
|
||||
|
||||
The project has two venues for real-time discussion:
|
||||
|
||||
* [`#nodejs-dev`](https://openjs-foundation.slack.com/archives/C019Y2T6STH) on
|
||||
the [OpenJS Foundation](https://slack-invite.openjsf.org/)
|
||||
|
||||
@ -71,7 +72,7 @@ The project has two venues for real-time discussion:
|
||||
* The best outcome is for people who come to our issue tracker to feel like
|
||||
they can come back again.
|
||||
|
||||
* You are expected to follow *and* hold others accountable to the
|
||||
* You are expected to follow _and_ hold others accountable to the
|
||||
[Code of Conduct][].
|
||||
|
||||
## Managing the issue tracker
|
||||
@ -88,7 +89,7 @@ The project has two venues for real-time discussion:
|
||||
not perfect, of course. Feel free to apply relevant labels and remove
|
||||
irrelevant labels from pull requests and issues.
|
||||
* `semver-{minor,major}`:
|
||||
* If a change has the remote *chance* of breaking something, use the
|
||||
* If a change has the remote _chance_ of breaking something, use the
|
||||
`semver-major` label
|
||||
* When adding a `semver-*` label, add a comment explaining why you're adding
|
||||
it. Do it right away so you don't forget!
|
||||
@ -113,20 +114,26 @@ The project has two venues for real-time discussion:
|
||||
## Reviewing pull requests
|
||||
|
||||
* The primary goal is for the codebase to improve.
|
||||
|
||||
* Secondary (but not far off) is for the person submitting code to succeed. A
|
||||
pull request from a new contributor is an opportunity to grow the community.
|
||||
|
||||
* Review a bit at a time. Do not overwhelm new contributors.
|
||||
* It is tempting to micro-optimize. Don't succumb to that temptation. We
|
||||
change V8 often. Techniques that provide improved performance today may be
|
||||
unnecessary in the future.
|
||||
|
||||
* Be aware: Your opinion carries a lot of weight!
|
||||
|
||||
* Nits (requests for small changes that are not essential) are fine, but try to
|
||||
avoid stalling the pull request.
|
||||
* Identify them as nits when you comment: `Nit: change foo() to bar().`
|
||||
* If they are stalling the pull request, fix them yourself on merge.
|
||||
|
||||
* Insofar as possible, issues should be identified by tools rather than human
|
||||
reviewers. If you are leaving comments about issues that could be identified
|
||||
by tools but are not, consider implementing the necessary tooling.
|
||||
|
||||
* Minimum wait for comments time
|
||||
* There is a minimum waiting time which we try to respect for non-trivial
|
||||
changes so that people who may have important input in such a distributed
|
||||
@ -134,6 +141,7 @@ The project has two venues for real-time discussion:
|
||||
* For non-trivial changes, leave the pull request open for at least 48 hours.
|
||||
* If a pull request is abandoned, check if they'd mind if you took it over
|
||||
(especially if it just has nits left).
|
||||
|
||||
* Approving a change
|
||||
* Collaborators indicate that they have reviewed and approve of the changes in
|
||||
a pull request using GitHub’s approval interface
|
||||
@ -159,7 +167,7 @@ The project has two venues for real-time discussion:
|
||||
such as `async_hooks`.
|
||||
|
||||
* Continuous Integration (CI) Testing:
|
||||
* [https://ci.nodejs.org/](https://ci.nodejs.org/)
|
||||
* <https://ci.nodejs.org/>
|
||||
* It is not automatically run. You need to start it manually.
|
||||
* Log in on CI is integrated with GitHub. Try to log in now!
|
||||
* You will be using `node-test-pull-request` most of the time. Go there now!
|
||||
@ -228,12 +236,12 @@ needs to be pointed out separately during the onboarding.
|
||||
* Almost any mistake you could make can be fixed or reverted.
|
||||
* The existing collaborators trust you and are grateful for your help!
|
||||
* Other repositories:
|
||||
* [https://github.com/nodejs/TSC](https://github.com/nodejs/TSC)
|
||||
* [https://github.com/nodejs/build](https://github.com/nodejs/build)
|
||||
* [https://github.com/nodejs/nodejs.org](https://github.com/nodejs/nodejs.org)
|
||||
* [https://github.com/nodejs/readable-stream](https://github.com/nodejs/readable-stream)
|
||||
* [https://github.com/nodejs/LTS](https://github.com/nodejs/LTS)
|
||||
* [https://github.com/nodejs/citgm](https://github.com/nodejs/citgm)
|
||||
* <https://github.com/nodejs/TSC>
|
||||
* <https://github.com/nodejs/build>
|
||||
* <https://github.com/nodejs/nodejs.org>
|
||||
* <https://github.com/nodejs/readable-stream>
|
||||
* <https://github.com/nodejs/LTS>
|
||||
* <https://github.com/nodejs/citgm>
|
||||
* The OpenJS Foundation hosts regular summits for active contributors to the
|
||||
Node.js project, where we have face-to-face discussions about our work on the
|
||||
project. The Foundation has travel funds to cover participants' expenses
|
||||
|
||||
Loading…
Reference in New Issue
Block a user