electron/node-gyp
1
0
Fork 0
mirror of https://github.com/electron/node-gyp.git synced 2025-08-15 12:58:19 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: README.md Do not hardcode the supported versions of Python (#2880)

Browse source
This commit is contained in:
Christian Clauss 2023-08-25 15:04:27 +02:00 • committed by GitHub
parent 0f1f667b73
commit bb93b946a9
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 24 additions and 123 deletions
Download patch file Download diff file Expand all files Collapse all files

3
.github/workflows/tests.yml vendored
View file

@ -13,8 +13,9 @@ jobs:
steps: steps:
- uses: actions/checkout@v3 - uses: actions/checkout@v3
- run: pip install --user ruff - run: pip install --user ruff
- run: ruff --format=github --select="E,F,PLC,PLE,UP,W,YTT" --ignore="PLC1901,S101,UP031" --target-version=py37 . - run: ruff --format=github --select="E,F,PLC,PLE,UP,W,YTT" --ignore="E721,PLC1901,S101,UP031" --target-version=py38 .
Tests: Tests:
needs: Lint_Python # Lint_Python takes ~5 seconds, so wait for it to pass before running the full matrix of tests.
strategy: strategy:
fail-fast: false fail-fast: false
max-parallel: 15 max-parallel: 15

40
README.md
View file

@ -6,7 +6,8 @@
`node-gyp` is a cross-platform command-line tool written in Node.js for `node-gyp` is a cross-platform command-line tool written in Node.js for
compiling native addon modules for Node.js. It contains a vendored copy of the compiling native addon modules for Node.js. It contains a vendored copy of the
[gyp-next](https://github.com/nodejs/gyp-next) project that was previously used [gyp-next](https://github.com/nodejs/gyp-next) project that was previously used
by the Chromium team, extended to support the development of Node.js native addons. by the Chromium team and extended to support the development of Node.js native
addons.
Note that `node-gyp` is _not_ used to build Node.js itself. Note that `node-gyp` is _not_ used to build Node.js itself.
@ -31,15 +32,13 @@ Depending on your operating system, you will need to install:
### On Unix ### On Unix
* Python v3.7, v3.8, v3.9, or v3.10 * [A supported version of Python](https://devguide.python.org/versions/)
* `make` * `make`
* A proper C/C++ compiler toolchain, like [GCC](https://gcc.gnu.org) * A proper C/C++ compiler toolchain, like [GCC](https://gcc.gnu.org)
### On macOS ### On macOS
**ATTENTION**: If your Mac has been _upgraded_ to macOS Catalina (10.15) or higher, please read [macOS_Catalina.md](macOS_Catalina.md). * [A supported version of Python](https://devguide.python.org/versions/)
* Python v3.7, v3.8, v3.9, or v3.10
* `XCode Command Line Tools` which will install `clang`, `clang++`, and `make`. * `XCode Command Line Tools` which will install `clang`, `clang++`, and `make`.
* Install the `XCode Command Line Tools` standalone by running `xcode-select --install`. -- OR -- * Install the `XCode Command Line Tools` standalone by running `xcode-select --install`. -- OR --
* Alternatively, if you already have the [full Xcode installed](https://developer.apple.com/xcode/download/), you can install the Command Line Tools under the menu `Xcode -> Open Developer Tool -> More Developer Tools...`. * Alternatively, if you already have the [full Xcode installed](https://developer.apple.com/xcode/download/), you can install the Command Line Tools under the menu `Xcode -> Open Developer Tool -> More Developer Tools...`.
@ -47,7 +46,8 @@ Depending on your operating system, you will need to install:
### On Windows ### On Windows
Install the current version of Python from the [Microsoft Store package](https://www.microsoft.com/en-us/p/python-310/9pjpw5ldxlz5). Install the current [version of Python](https://devguide.python.org/versions/) from the
[Microsoft Store](https://apps.microsoft.com/store/search?publisher=Python+Software+Foundation).
Install tools and configuration manually: Install tools and configuration manually:
* Install Visual C++ Build Environment: [Visual Studio Build Tools](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools) * Install Visual C++ Build Environment: [Visual Studio Build Tools](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools)
@ -62,9 +62,9 @@ Install tools and configuration manually:
### Configuring Python Dependency ### Configuring Python Dependency
`node-gyp` requires that you have installed a compatible version of Python, one of: v3.7, v3.8, `node-gyp` requires that you have installed a [supported version of Python](https://devguide.python.org/versions/).
v3.9, or v3.10. If you have multiple Python versions installed, you can identify which Python If you have multiple versions of Python installed, you can identify which version
version `node-gyp` should use in one of the following ways: `node-gyp` should use in one of the following ways:
1. by setting the `--python` command-line option, e.g.: 1. by setting the `--python` command-line option, e.g.:
@ -73,24 +73,28 @@ node-gyp <command> --python /path/to/executable/python
``` ```
2. If `node-gyp` is called by way of `npm`, *and* you have multiple versions of 2. If `node-gyp` is called by way of `npm`, *and* you have multiple versions of
Python installed, then you can set `npm`'s 'python' config key to the appropriate Python installed, then you can set the `npm_config_python` environment variable
value: to the appropriate path:
``` bash ``` bash
npm config set python /path/to/executable/python export npm_config_python=/path/to/executable/python
```
&nbsp;&nbsp;&nbsp;&nbsp;Or on Windows:
```console
py --list-paths # To see the installed Python versions
set npm_config_python=C:\path\to\python.exe
``` ```
3. If the `PYTHON` environment variable is set to the path of a Python executable, 3. If the `PYTHON` environment variable is set to the path of a Python executable,
then that version will be used, if it is a compatible version. then that version will be used if it is a supported version.
4. If the `NODE_GYP_FORCE_PYTHON` environment variable is set to the path of a 4. If the `NODE_GYP_FORCE_PYTHON` environment variable is set to the path of a
Python executable, it will be used instead of any of the other configured or Python executable, it will be used instead of any of the other configured or
builtin Python search paths. If it's not a compatible version, no further built-in Python search paths. If it's not a compatible version, no further
searching will be done. searching will be done.
### Build for Third Party Node.js Runtimes ### Build for Third Party Node.js Runtimes
When building modules for third party Node.js runtimes like Electron, which have When building modules for third-party Node.js runtimes like Electron, which have
different build configurations from the official Node.js distribution, you different build configurations from the official Node.js distribution, you
should use `--dist-url` or `--nodedir` flags to specify the headers of the should use `--dist-url` or `--nodedir` flags to specify the headers of the
runtime to build for. runtime to build for.
@ -106,7 +110,7 @@ to work around configuration errors.
## How to Use ## How to Use
To compile your native addon, first go to its root directory: To compile your native addon first go to its root directory:
``` bash ``` bash
cd my_node_addon cd my_node_addon
@ -240,7 +244,7 @@ Or this on Windows:
set npm_config_devdir=c:\temp\.gyp set npm_config_devdir=c:\temp\.gyp
``` ```
### `npm` configuration ### `npm` configuration for npm versions before v9
Use the form `OPTION_NAME` for any of the command options listed above. Use the form `OPTION_NAME` for any of the command options listed above.

104
macOS_Catalina.md
View file

@ -1,104 +0,0 @@
# Installation notes for macOS Catalina (v10.15)
_This document specifically refers to upgrades from previous versions of macOS to Catalina (10.15). It should be removed from the source repository when Catalina ceases to be the latest macOS version or when future Catalina versions no longer raise these issues._
**Both upgrading to macOS Catalina and running a Software Update in Catalina may cause normal `node-gyp` installations to fail. This might manifest as the following error during `npm install`:**
```console
gyp: No Xcode or CLT version detected!
```
## node-gyp v7
The newest release of `node-gyp` should solve this problem. If you are using `node-gyp` directly then you should be able to install v7 and use it as-is.
If you need to use `node-gyp` from within `npm` (e.g. through `npm install`), you will have to install `node-gyp` (either globally with `-g` or to a predictable location) and tell `npm` where the new version is. Either use:
* `npm config set node_gyp <path to node-gyp>`; or
* run `npm` with an environment variable prefix: `npm_config_node_gyp=<path to node-gyp> npm install`
Where "path to node-gyp" is to the `node-gyp` executable which may be a symlink in your global bin directory (e.g. `/usr/local/bin/node-gyp`), or a path to the `node-gyp` installation directory and the `bin/node-gyp.js` file within it (e.g. `/usr/local/lib/node_modules/node-gyp/bin/node-gyp.js`).
**If you use `npm config set` to change your global `node_gyp` you are responsible for keeping it up to date and can't rely on `npm` to give you a newer version when available.** Use `npm config delete node_gyp` to unset this configuration option.
## Fixing Catalina for older versions of `node-gyp`
### Is my Mac running macOS Catalina?
Let's first make sure that your Mac is running Catalina:
```
% sw_vers
ProductName: Mac OS X
ProductVersion: 10.15
BuildVersion: 19A602
```
If `ProductVersion` is less then `10.15` then this document is not for you. Normal install docs for `node-gyp` on macOS can be found at https://github.com/nodejs/node-gyp#on-macos
### The acid test
To see if `Xcode Command Line Tools` is installed in a way that will work with `node-gyp`, run:
```
curl -sL https://github.com/nodejs/node-gyp/raw/main/macOS_Catalina_acid_test.sh | bash
```
If test succeeded, _you are done_! You should be ready to [install](https://github.com/nodejs/node-gyp#installation) `node-gyp`.
If test failed, there is a problem with your Xcode Command Line Tools installation. [Continue to Solutions](#Solutions).
### Solutions
There are three ways to install the Xcode libraries `node-gyp` needs on macOS. People running Catalina have had success with some but not others in a way that has been unpredictable.
1. With the full Xcode (~7.6 GB download) from the `App Store` app.
2. With the _much_ smaller Xcode Command Line Tools via `xcode-select --install`
3. With the _much_ smaller Xcode Command Line Tools via manual download. **For people running the latest version of Catalina (10.15.2 at the time of this writing), this has worked when the other two solutions haven't.**
### Installing `node-gyp` using the full Xcode
1. `xcodebuild -version` should show `Xcode 11.1` or later.
* If not, then install/upgrade Xcode from the App Store app.
2. Open the Xcode app and...
* Under __Preferences > Locations__ select the tools if their location is empty.
* Allow Xcode app to do an essential install of the most recent compiler tools.
3. Once all installations are _complete_, quit out of Xcode.
4. `sudo xcodebuild -license accept` # If you agree with the licensing terms.
5. `softwareupdate -l` # No listing is a good sign.
* If Xcode or Tools upgrades are listed, use "Software Upgrade" to install them.
6. `xcode-select -version` # Should return `xcode-select version 2370` or later.
7. `xcode-select -print-path` # Should return `/Applications/Xcode.app/Contents/Developer`
8. Try the [_acid test_ steps above](#The-acid-test) to see if your Mac is ready.
9. If the _acid test_ does _not_ pass then...
10. `sudo xcode-select --reset` # Enter root password. No output is normal.
11. Repeat step 7 above. Is the path different this time? Repeat the _acid test_.
### Installing `node-gyp` using the Xcode Command Line Tools via `xcode-select --install`
1. If the _acid test_ has not succeeded, then try `xcode-select --install`
2. If the installation command returns `xcode-select: error: command line tools are already installed, use "Software Update" to install updates`, continue to [remove and reinstall](#i-did-all-that-and-the-acid-test-still-does-not-pass--)
3. Wait until the install process is _complete_.
4. `softwareupdate -l` # No listing is a good sign.
* If Xcode or Tools upgrades are listed, use "Software Update" to install them.
5. `xcode-select -version` # Should return `xcode-select version 2370` or later.
6. `xcode-select -print-path` # Should return `/Library/Developer/CommandLineTools`
7. Try the [_acid test_ steps above](#The-acid-test) to see if your Mac is ready.
8. If the _acid test_ does _not_ pass then...
9. `sudo xcode-select --reset` # Enter root password. No output is normal.
10. Repeat step 5 above. Is the path different this time? Repeat the _acid test_.
### Installing `node-gyp` using the Xcode Command Line Tools via manual download
1. Download the appropriate version of the "Command Line Tools for Xcode" for your version of Catalina from <https://developer.apple.com/download/more/>. As of MacOS 10.15.5, that's [Command_Line_Tools_for_Xcode_11.5.dmg](https://download.developer.apple.com/Developer_Tools/Command_Line_Tools_for_Xcode_11.5/Command_Line_Tools_for_Xcode_11.5.dmg)
2. Install the package.
3. Run the [_acid test_ steps above](#The-acid-test).
### I did all that and the acid test still does not pass :-(
1. `sudo rm -rf $(xcode-select -print-path)` # Enter root password. No output is normal.
2. `sudo rm -rf /Library/Developer/CommandLineTools` # Enter root password.
3. `sudo xcode-select --reset`
4. `xcode-select --install`
5. If the [_acid test_ steps above](#The-acid-test) still does _not_ pass then...
6. `npm explore npm -g -- npm install node-gyp@latest`
7. `npm explore npm -g -- npm explore npm-lifecycle -- npm install node-gyp@latest`
8. If the _acid test_ still does _not_ pass then...
9. Add a comment to https://github.com/nodejs/node-gyp/issues/1927 so we can improve.
Lessons learned from:
* https://github.com/nodejs/node-gyp/issues/1779
* https://github.com/nodejs/node-gyp/issues/1861
* https://github.com/nodejs/node-gyp/issues/1927 and elsewhere
* Thanks to @rrrix for discovering Solution 3