### Example Error Log from npm Install

Source: https://github.com/nodejs/node-gyp/blob/main/docs/Error-pre-versions-of-node-cannot-be-installed.md

This log shows the typical error output when `npm install` fails due to a 'pre' version of Node.js.

```bash
$ npm install bcrypt
npm http GET https://registry.npmjs.org/bcrypt/0.7.5
npm http 304 https://registry.npmjs.org/bcrypt/0.7.5
npm http GET https://registry.npmjs.org/bindings/1.0.0
npm http 304 https://registry.npmjs.org/bindings/1.0.0

> bcrypt@0.7.5 install /home/ubuntu/public/song-swap/node_modules/bcrypt
> node-gyp rebuild

gyp ERR! configure error
gyp ERR! stack Error: "pre" versions of node cannot be installed, use the --nodedir flag instead
gyp ERR! stack     at install (/usr/local/lib/node_modules/npm/node_modules/node-gyp/lib/install.js:69:16)
gyp ERR! stack     at Object.self.commands.(anonymous function) [as install] (/usr/local/lib/node_modules/npm/node_modules/node-gyp/lib/node-gyp.js:56:37)
gyp ERR! stack     at getNodeDir (/usr/local/lib/node_modules/npm/node_modules/node-gyp/lib/configure.js:219:20)
gyp ERR! stack     at /usr/local/lib/node_modules/npm/node_modules/node-gyp/lib/configure.js:105:9
gyp ERR! stack     at ChildProcess.exithandler (child_process.js:630:7)
gyp ERR! stack     at ChildProcess.EventEmitter.emit (events.js:99:17)
gyp ERR! stack     at maybeClose (child_process.js:730:16)
gyp ERR! stack     at Process.ChildProcess._handle.onexit (child_process.js:797:5)
gyp ERR! System Linux 3.5.0-21-generic
gyp ERR! command "node" "/usr/local/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js" "rebuild"
gyp ERR! cwd /home/ubuntu/public/song-swap/node_modules/bcrypt
gyp ERR! node -v v0.11.2-pre
gyp ERR! node-gyp -v v0.9.5
gyp ERR! not ok
npm ERR! bcrypt@0.7.5 install: `node-gyp rebuild`
npm ERR! `sh "-c" "node-gyp rebuild"` failed with 1
npm ERR! 
npm ERR! Failed at the bcrypt@0.7.5 install script.
npm ERR! This is most likely a problem with the bcrypt package,
npm ERR! not with npm itself.
npm ERR! Tell the author that this fails on your system:
npm ERR!     node-gyp rebuild
npm ERR! You can get their info via:
npm ERR!     npm owner ls bcrypt
npm ERR! There is likely additional logging output above.

npm ERR! System Linux 3.5.0-21-generic
npm ERR! command "/usr/local/bin/node" "/usr/local/bin/npm" "install" "bcrypt"
npm ERR! cwd /home/ubuntu/public/song-swap
npm ERR! node -v v0.11.2-pre
npm ERR! npm -v 1.2.18
npm ERR! code ELIFECYCLE
npm ERR! 
npm ERR! Additional logging details can be found in:
npm ERR!     /home/ubuntu/public/song-swap/npm-debug.log
npm ERR! not ok code 0
```

--------------------------------

### Install gyp-next using uv

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/README.md

Install the gyp-next package using uv. This is an alternative package manager for Python.

```bash
uv tool install gyp-next
```

--------------------------------

### Install global node-gyp on Linux/macOS

Source: https://github.com/nodejs/node-gyp/blob/main/docs/Force-npm-to-use-global-node-gyp.md

Installs the latest version of node-gyp globally. Sudo may be required.

```bash
npm install --global node-gyp@latest
```

--------------------------------

### Install Development Dependencies and Run Tests

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/Hacking.md

Install the necessary development dependencies using pip and then run the test suite with pytest. Ensure your pip is up-to-date.

```sh
python -m pip install --upgrade pip
pip install --editable ".[dev]"
python -m pytest
```

--------------------------------

### Install node-gyp globally

Source: https://github.com/nodejs/node-gyp/blob/main/README.md

Installs the node-gyp package globally using npm. Ensure you have Node.js and npm installed.

```bash
npm install -g node-gyp
```

--------------------------------

### Install gyp-next using pip

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/README.md

Install the gyp-next package using pip for Python 3. This command installs the package globally.

```bash
python3 -m pip install gyp-next
```

--------------------------------

### Example List of Strings

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/InputFormatReference.md

Demonstrates a list containing three string values. Trailing commas are permitted.

```gyp
[
  'Generate',
  'Your',
  'Projects',
]
```

--------------------------------

### Command Expansion Example

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/InputFormatReference.md

Illustrates command expansions using '<!' for string output and '<!@' for list output, showing how shell commands are integrated into the build process.

```python
{
  'sources': [
    '!(echo filename with space.cc)',
  ],
  'libraries': [
    '!@(pkg-config --libs-only-l apr-1)',
  ],
}
```

```python
{
  'sources': [
    'filename with space.cc',  # no @, expands into a single string
  ],
  'libraries': [  # @ was used, so there's a separate list item for each lib
    '-lapr-1',
    '-lpthread',
  ],
}
```

--------------------------------

### Target Dictionary Example

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/InputFormatReference.md

A simple target dictionary containing source files.

```gyp
{
  'sources': ['string_util.cc'],
}

```

--------------------------------

### List Directory Contents for Test Setup

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/Testing.md

Shows the file structure for a simple 'Hello, world!' GYP test case, including the C source, GYP configuration, and test scripts.

```bash
  $ ls -l test/hello
total 20
-rw-r--r-- 1 knight knight 312 Jul 30 20:22 gyptest-all.py
-rw-r--r-- 1 knight knight 307 Jul 30 20:22 gyptest-default.py
-rwxr-xr-x 1 knight knight 326 Jul 30 20:22 gyptest-target.py
-rw-r--r-- 1 knight knight  98 Jul 30 20:22 hello.c
-rw-r--r-- 1 knight knight 142 Jul 30 20:22 hello.gyp
$

```

--------------------------------

### Node-gyp Configuration Example

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/LanguageSpecification.md

This snippet demonstrates a typical Node-gyp configuration structure, including target defaults, target definitions, sources, include directories, and conditional settings.

```python
{
  'target_defaults': {
    'defines': [
      'U_STATIC_IMPLEMENTATION',
      ['LOGFILE', 'foo.log',],
    ],
    'include_dirs': [
      '..',
    ],
  },
  'targets': [
    {
      'target_name': 'foo',
      'type': 'static_library',
      'sources': [
        'foo/src/foo.cc',
        'foo/src/foo_main.cc',
      ],
      'include_dirs': [
         'foo',
         'foo/include',
      ],
      'conditions': [
         [ 'OS==mac', { 'sources': [ 'platform_test_mac.mm' ] } ]
      ],
      'direct_dependent_settings': {
        'defines': [
          'UNIT_TEST',
        ],
        'include_dirs': [
          'foo',
          'foo/include',
        ],
      },
    },
  ],
}
```

--------------------------------

### Overriding openssl-root on Windows

Source: https://github.com/nodejs/node-gyp/blob/main/docs/Linking-to-OpenSSL.md

Demonstrates how to specify a custom OpenSSL installation path on Windows using the `node-gyp` command line.

```bash
$ node-gyp rebuild --openssl-root="C:\Users\Nathan\Desktop\openssl"
```

--------------------------------

### Source Dictionary Example

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/InputFormatReference.md

Illustrates how pathnames are treated relative to the file they are defined in. Note that '-lz' is not treated as a pathname.

```gyp
{
  'include_dirs': ['include'],  # Treated as relative to ../build
  'library_dirs': ['lib'],      # Treated as relative to ../build
  'libraries': ['-lz'],   # Not treated as a pathname, begins with a dash
  'defines': ['NDEBUG'],  # defines does not contain pathnames
}

```

--------------------------------

### Variable Expansion Examples

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/InputFormatReference.md

Demonstrates the usage of early (<) and late (>) variable expansions, including string and list contexts.

```python
'variables' : [
  'foo': '<!(echo Build Date <!(date))',
],
```

```python
'variables' : [
  'foo': 'Build Date 02:10:38 PM Fri Jul 24, 2009 -0700 PDT',
],
```

```python
'variables' : [
  'files': '<!(["ls", "-1", "Filename With Spaces"])',
],
```

--------------------------------

### Singleton List Item Merging Example

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/InputFormatReference.md

Demonstrates how string items in lists that do not start with a dash are treated as singletons. If an item already exists, only the first occurrence is kept during merging.

```python
{
  'defines': [
    'EXPERIMENT=1',
    'NDEBUG',
  ],
}
```

```python
{
  'defines': [
    'NDEBUG',
    'USE_THREADS',
  ],
}
```

```python
{
  'defines': [
    'NDEBUG',
    'USE_THREADS',
    'EXPERIMENT=1',
  ],
}
```

--------------------------------

### Install gyp-next using pipx

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/README.md

Install the gyp-next package using pipx. This method is suitable for managing Python applications.

```bash
pipx install gyp-next 
```

--------------------------------

### GYP Merge Example: List Append and Prepend

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/InputFormatReference.md

Illustrates how lists are merged. The '+' suffix prepends source list items, while undecorated list keys append source list items. This example shows merging include directories and libraries.

```gyp
{
  'include_dirs+': [
    'shared_stuff/public',
  ],
  'link_settings': {
    'libraries': [
      '-lshared_stuff',
    ],
  },
  'test': 1,
}
```

```gyp
{
  'target_name': 'hello',
  'sources': [
    'kitty.cc',
  ],
  'include_dirs': [
    'headers',
  ],
  'link_settings': {
    'libraries': [
      '-lm',
    ],
    'library_dirs': [
      '/usr/lib',
    ],
  },
  'test': 0,
}
```

```gyp
{
  'target_name': 'hello',
  'sources': [
    'kitty.cc',
  ],
  'include_dirs': [
    'shared_stuff/public',  # Merged, list item prepended due to include_dirs+
    'headers',
  ],
  'link_settings': {
    'libraries': [
      '-lm',
      '-lshared_stuff',  # Merged, list item appended
    ],
    'library_dirs': [
      '/usr/lib',
    ],
  },
  'test': 1,  # Merged, int value replaced
}
```

--------------------------------

### Install node-gyp dependencies on Windows with Chocolatey

Source: https://github.com/nodejs/node-gyp/blob/main/README.md

Installs Python and Visual Studio build tools on Windows using the Chocolatey package manager. The '-y' flag automatically confirms prompts.

```bash
choco install python visualstudio2022-workload-vctools -y
```

--------------------------------

### Specify Multiple Build Tools with -f Option

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/Testing.md

Specify multiple build tools as a comma-separated list with the -f option. This example uses 'make' and 'scons'.

```bash
  $ python gyptest.py -f make,scons test/hello/gyptest-all.py
  PYTHONPATH=/home/knight/src/gyp/trunk/test/lib
  TESTGYP_FORMAT=make
  /usr/bin/python test/hello/gyptest-all.py
  PASSED
  TESTGYP_FORMAT=scons
  /usr/bin/python test/hello/gyptest-all.py
  PASSED
  $
```

--------------------------------

### Uninstall and Install Sass

Source: https://github.com/nodejs/node-gyp/blob/main/docs/README.md

Use these commands to uninstall the deprecated node-sass package and install the recommended 'sass' package.

```bash
npm uninstall node-sass
npm install sass --save
```

```bash
npm install --global node-sass@latest
```

--------------------------------

### Run gyp-next directly using pipx

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/README.md

Execute the gyp-next command directly without a formal installation using pipx.

```bash
pipx run gyp-next --help 
```

--------------------------------

### Merged Dictionary Example

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/InputFormatReference.md

Shows the result of merging dictionaries, demonstrating how relative pathnames are adjusted to remain valid relative to the new file's location.

```gyp
{
  'sources': ['string_util.cc'],
  'include_dirs': ['../build/include'],
  'library_dirs': ['../build/lib'],
  'libraries': ['-lz'],
  'defines': ['NDEBUG'],
}

```

--------------------------------

### GYP Target with Dependent Settings Example

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/InputFormatReference.md

Defines a static library 'cruncher' and an executable 'cruncher_test' that depends on it. 'cruncher' advertises include directories and link libraries to its dependents.

```python
{
  'targets': [
    {
      'target_name': 'cruncher',
      'type': 'static_library',
      'sources': ['cruncher.cc'],
      'direct_dependent_settings': {
        'include_dirs': ['.'],  # dependents need to find cruncher.h.
      },
      'link_settings': {
        'libraries': ['-lm'],  # cruncher.cc does math.
      },
    },
    {
      'target_name': 'cruncher_test',
      'type': 'executable',
      'dependencies': ['cruncher'],
      'sources': ['cruncher_test.cc'],
    },
  ],
}
```

--------------------------------

### Checking Node.js Version

Source: https://github.com/nodejs/node-gyp/blob/main/docs/Error-pre-versions-of-node-cannot-be-installed.md

Verify your Node.js version to confirm if it's a 'pre' release, which can cause installation issues.

```bash
$ node -v
v0.10.4-pre
```

--------------------------------

### Specify Build Tool with -f Option

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/Testing.md

Use the -f option to specify the build tool format for gyptest.py. This example shows using 'make'.

```bash
  $ python gyptest.py -f make test/hello/gyptest-all.py
  PYTHONPATH=/home/knight/src/gyp/trunk/test/lib
  TESTGYP_FORMAT=make
  /usr/bin/python test/hello/gyptest-all.py
  PASSED
  $
```

--------------------------------

### Example Dictionary with Mixed Types

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/InputFormatReference.md

Illustrates a dictionary mapping string keys to different value types, including a list and an integer. Trailing commas are permitted.

```gyp
{
  'inputs': ['version.c.in'],
  'outputs': ['version.c'],
  'process_outputs_as_sources': 1,
}
```

--------------------------------

### Define a Platform-Specific Library Target

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/UserDocumentation.md

Add a library target within a 'conditions' block to make it platform-specific. This example defines 'new_library' only for Windows (OS=="win").

```gyp
  {
    'targets': [
    ],
    'conditions': [
      ['OS=="win"', {
        'targets': [
          {
            'target_name': 'new_library',
            'type': '<(library)',
            'defines': [
              'FOO',
              'BAR=some_value',
            ],
            'include_dirs': [
              '..',
            ],
            'dependencies': [
              'other_target_in_this_file',
              'other_gyp2:target_in_other_gyp2',
            ],
            'direct_dependent_settings': {
              'include_dirs': '.',
            },
            'export_dependent_settings': [
              'other_target_in_this_file',
            ],
            'sources': [
              'new_additional_source.cc',
              'new_library.cc',
            ],
          },
        ],
      }],
    ],
  }
```

--------------------------------

### Configure npm to use global node-gyp on Windows Command Prompt

Source: https://github.com/nodejs/node-gyp/blob/main/docs/Force-npm-to-use-global-node-gyp.md

Sets the 'node_gyp' configuration to point to the globally installed node-gyp executable using a for loop. This ensures npm uses the global version for building native addons.

```batch
for /f "delims=" %P in ('npm prefix -g') do npm config set node_gyp "%P\node_modules\node-gyp\bin\node-gyp.js"
```

--------------------------------

### Fixing Node-gyp Installation with --nodedir

Source: https://github.com/nodejs/node-gyp/blob/main/docs/Error-pre-versions-of-node-cannot-be-installed.md

When using 'pre' versions of Node.js, specify the path to your Node.js source code directory using the `--nodedir` flag with `node-gyp`.

```bash
$ node-gyp rebuild --nodedir=/Users/nrajlich/node
```

```bash
$ npm install bcrypt --nodedir=/Users/nrajlich/node
```

--------------------------------

### GYP Comment Example

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/InputFormatReference.md

Demonstrates how comments are introduced by a pound sign (#) and are ignored if not within a string. Comments are ignored by the parser.

```gyp
{
  'school_supplies': [
    'Marble composition book',
    'Sharp #2 pencil',
    'Safety scissors',  # You still shouldn't run with these
  ],
}
```

--------------------------------

### Configure npm to use global node-gyp on Linux/macOS

Source: https://github.com/nodejs/node-gyp/blob/main/docs/Force-npm-to-use-global-node-gyp.md

Sets the 'node_gyp' configuration to point to the globally installed node-gyp executable. This ensures npm uses the global version for building native addons.

```bash
npm config set node_gyp $(npm prefix -g)/lib/node_modules/node-gyp/bin/node-gyp.js
```

--------------------------------

### Configure npm to use global node-gyp on Windows PowerShell

Source: https://github.com/nodejs/node-gyp/blob/main/docs/Force-npm-to-use-global-node-gyp.md

Sets the 'node_gyp' configuration to point to the globally installed node-gyp executable using PowerShell piping. This ensures npm uses the global version for building native addons.

```powershell
npm prefix -g | % {npm config set node_gyp "$_
ode_modules
ode-gypin
ode-gyp.js"}
```

--------------------------------

### binding.gyp for Windows OpenSSL Linking

Source: https://github.com/nodejs/node-gyp/blob/main/docs/Linking-to-OpenSSL.md

This configuration enables linking to a separate OpenSSL installation on Windows. It sets default paths for 32-bit and 64-bit builds and can be overridden via the command line.

```python
    [ 'OS=="win"', {
      'conditions': [
        # "openssl_root" is the directory on Windows of the OpenSSL files.
        # Check the "target_arch" variable to set good default values for
        # both 64-bit and 32-bit builds of the module.
        ['target_arch=="x64"', {
          'variables': {
            'openssl_root%': 'C:/OpenSSL-Win64'
          },
        }, {
          'variables': {
            'openssl_root%': 'C:/OpenSSL-Win32'
          },
        }],
      ],
      'libraries': [ 
        '-l<(openssl_root)/lib/libeay32.lib',
      ],
      'include_dirs': [
        '<(openssl_root)/include',
      ],
    }]
```

--------------------------------

### GYP Example: Target Conditions for Shared Libraries

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/InputFormatReference.md

Demonstrates the use of 'target_conditions' to apply flags like '-fPIC' specifically to shared libraries. This ensures that conditional logic is evaluated only within the target context.

```json
{
  'target_defaults': {
    'target_conditions': [
      ['_type=="shared_library"', {'cflags': ['-fPIC']}],
    ],
  },
  'targets': [
    {
      'target_name': 'sharing_is_caring',
      'type': 'shared_library',
    },
    {
      'target_name': 'static_in_the_attic',
      'type': 'static_library',
    },
  ]
}
```

```json
{
  'targets': [
    {
      'target_name': 'sharing_is_caring',
      'type': 'shared_library',
      'cflags': ['-fPIC'],
    },
    {
      'target_name': 'static_in_the_attic',
      'type': 'static_library',
    },
  ]
}
```

--------------------------------

### Initialize TestGyp with Regex Matching

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/Testing.md

Initialize TestGyp with regex matching for output and diff comparisons. Use when exact matches are not sufficient.

```python
  import TestGyp
  test = TestGyp.TestGyp(match = TestGyp.match_re,
                         diff = TestGyp.diff_re)
```

--------------------------------

### GYP Test Script: 'Hello, world!' with 'all' target

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/Testing.md

A GYP test script that verifies the simplest possible build of a 'Hello, world!' program using an explicit build target of 'all'. It runs GYP, builds the target, and verifies the executable's output.

```python
  #!/usr/bin/env python

  """
  Verifies simplest-possible build of a "Hello, world!" program
  using an explicit build target of 'all'.
  """

  import TestGyp

  test = TestGyp.TestGyp()

  test.run_gyp('hello.gyp')

  test.build_all('hello.gyp')

  test.run_built_executable('hello', stdout="Hello, world!\n")

  test.pass_test()

```

--------------------------------

### Get Standard Output

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/Testing.md

Retrieve the standard output from the most recently executed command.

```python
  test.stdout()
```

--------------------------------

### Configure Node-Gyp Build Files

Source: https://github.com/nodejs/node-gyp/blob/main/README.md

Generate platform-specific build files for your native addon. Use --msvs_version=2015 for Visual C++ Build Tools 2015 if auto-detection fails.

```bash
node-gyp configure
```

```bash
node-gyp configure --msvs_version=2015
```

--------------------------------

### Get Standard Error

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/Testing.md

Retrieve the standard error output from the most recently executed command.

```python
  test.stderr()
```

--------------------------------

### Uninstall global node-gyp

Source: https://github.com/nodejs/node-gyp/blob/main/docs/Force-npm-to-use-global-node-gyp.md

Uninstalls the globally installed node-gyp package. This should be done after deleting the 'node_gyp' configuration.

```bash
npm uninstall --global node-gyp
```

--------------------------------

### Build All Targets

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/Testing.md

Invoke the build tool to build all targets defined in the .gyp file.

```python
  test.build_all('file.gyp')
```

--------------------------------

### Build Native Addon

Source: https://github.com/nodejs/node-gyp/blob/main/README.md

Compile your native addon after configuration. The compiled .node file will be in build/Debug/ or build/Release/.

```bash
node-gyp build
```

--------------------------------

### Run gyp-next directly using uvx

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/README.md

Execute the gyp-next command directly using uvx, specifying the package source.

```bash
uvx --from=gyp-next gyp --help
```

--------------------------------

### Create Debug Build

Source: https://github.com/nodejs/node-gyp/blob/main/README.md

Pass the --debug or -d switch to configure, build, or rebuild commands to create a Debug build of the bindings file.

```bash
node-gyp configure --debug
```

```bash
node-gyp build -d
```

--------------------------------

### gyp command line options

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/README.md

Displays the help message and available options for the gyp command-line utility. This includes build configurations and file checking.

```bash
NOTE: running app 'gyp' from 'gyp-next'
usage: gyp [options ...] [build_file ...]

options:
  -h, --help            show this help message and exit
  --build CONFIGS       configuration for build after project generation
  --check               check format of gyp files
  [ ... ]
```

--------------------------------

### Find node.exe location on Windows

Source: https://github.com/nodejs/node-gyp/blob/main/docs/Updating-npm-bundled-node-gyp.md

On Windows, first locate the directory where node.exe is installed. This is necessary before navigating to the correct npm module directory.

```bash
$ where node
```

--------------------------------

### Skeleton of a Typical Chromium .gyp File

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/UserDocumentation.md

Illustrates the basic structure of a .gyp file, including variables, includes, target defaults, targets, and conditional configurations.

```python
{
    'variables': {
      .
      .
      .
    },
    'includes': [
      '../build/common.gypi',
    ],
    'target_defaults': {
      .
      .
      .
    },
    'targets': [
      {
        'target_name': 'target_1',
          .
          .
          .
      },
      {
        'target_name': 'target_2',
          .
          .
          .
      },
    ],
    'conditions': [
      ['OS=="linux"', {
        'targets': [
          {
            'target_name': 'linux_target_3',
              .
              .
              .
          },
        ],
      }],
      ['OS=="win"', {
        'targets': [
          {
            'target_name': 'windows_target_4',
              .
              .
              .
          },
        ],
      }, { # OS != "win"
        'targets': [
          {
            'target_name': 'non_windows_target_5',
              .
              .
              .
          },
      }],
    ],
  }
```

--------------------------------

### Running All GYP Tests in the Project Tree

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/Testing.md

Illustrates how to execute all GYP test scripts across the entire project tree using the `-a` option with `gyptest.py`.

```bash
  $ python gyptest.py -a
PYTHONPATH=/home/knight/src/gyp/trunk/test/lib
TESTGYP_FORMAT=scons
/usr/bin/python test/configurations/gyptest-configurations.py
PASSED
/usr/bin/python test/defines/gyptest-defines.py
PASSED
    .
    .
    .
    .
/usr/bin/python test/variables/gyptest-commands.py
PASSED
$

```

--------------------------------

### Navigate to Addon Directory

Source: https://github.com/nodejs/node-gyp/blob/main/README.md

Change to the root directory of your native addon before running node-gyp commands.

```bash
cd my_node_addon
```

--------------------------------

### Initialize TestGyp

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/Testing.md

Standard initialization for the TestGyp class. Copies test files to a temporary directory.

```python
  import TestGyp
  test = TestGyp.TestGyp()
```

--------------------------------

### Define Binding.gyp Configuration

Source: https://github.com/nodejs/node-gyp/blob/main/README.md

A barebones binding.gyp file in JSON-like format describes the configuration for building a Node.js addon, specifying targets and source files.

```python
{
  "targets": [
    {
      "target_name": "binding",
      "sources": [ "src/binding.cc" ]
    }
  ]
}
```

--------------------------------

### Executable Target Configuration

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/UserDocumentation.md

Defines a basic executable target with dependencies, preprocessor definitions, include directories, source files, and conditional settings for different operating systems.

```gyp
{
    'targets': [
      {
        'target_name': 'foo',
        'type': 'executable',
        'msvs_guid': '5ECEC9E5-8F23-47B6-93E0-C3B328B3BE65',
        'dependencies': [
          'xyzzy',
          '../bar/bar.gyp:bar',
        ],
        'defines': [
          'DEFINE_FOO',
          'DEFINE_A_VALUE=value',
        ],
        'include_dirs': [
          '..',
        ],
        'sources': [
          'file1.cc',
          'file2.cc',
        ],
        'conditions': [
          ['OS=="linux"', {
            'defines': [
              'LINUX_DEFINE',
            ],
            'include_dirs': [
              'include/linux',
            ],
          }],
          ['OS=="win"', {
            'defines': [
              'WINDOWS_SPECIFIC_DEFINE',
            ],
          }, { 
            'defines': [
              'NON_WINDOWS_DEFINE',
            ],
          }]
        ],
      },
    ],
  }
```

--------------------------------

### Add new include directories

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/UserDocumentation.md

Add new include directories for the compiler using the 'include_dirs' setting. Paths can be relative.

```gyp
{
    "targets": [
      {
        "target_name": "existing_target",
        "include_dirs": [
          "..",
          "include",
        ],
      },
    ],
  }
```

--------------------------------

### Add new preprocessor definitions

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/UserDocumentation.md

Add new preprocessor definitions using the 'defines' setting. These can be simple flags or key-value pairs.

```gyp
{
    "targets": [
      {
        "target_name": "existing_target",
        "defines": [
          "FOO",
          "BAR=some_value",
        ],
      },
    ],
  },
```

--------------------------------

### Set npm_config_python environment variable

Source: https://github.com/nodejs/node-gyp/blob/main/README.md

Configures the Python path for node-gyp when invoked via npm. This is useful when multiple Python versions are installed. For Windows CMD, use 'set'; for PowerShell, use '$Env:'.

```bash
export npm_config_python=/path/to/executable/python
```

```powershell
$Env:npm_config_python="C:\path\to\python.exe"
```

```cmd
set npm_config_python=C:\path\to\python.exe
```

--------------------------------

### Library Target Configuration in .gyp File

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/UserDocumentation.md

This snippet shows a typical library target configuration in a .gyp file, including dependencies, defines, include directories, and conditional settings based on the operating system.

```gyp
{
    'targets': [
      {
        'target_name': 'foo',
        'type': '<(library)'
        'msvs_guid': '5ECEC9E5-8F23-47B6-93E0-C3B328B3BE65',
        'dependencies': [
          'xyzzy',
          '../bar/bar.gyp:bar',
        ],
        'defines': [
          'DEFINE_FOO',
          'DEFINE_A_VALUE=value',
        ],
        'include_dirs': [
          '..',
        ],
        'direct_dependent_settings': {
          'defines': [
            'DEFINE_FOO',
            'DEFINE_ADDITIONAL',
          ],
          'linkflags': [
          ],
        },
        'export_dependent_settings': [
          '../bar/bar.gyp:bar',
        ],
        'sources': [
          'file1.cc',
          'file2.cc',
        ],
        'conditions': [
          ['OS=="linux"', {
            'defines': [
              'LINUX_DEFINE',
            ],
            'include_dirs': [
              'include/linux',
            ],
          ],
          ['OS=="win"', {
            'defines': [
              'WINDOWS_SPECIFIC_DEFINE',
            ],
          }, { # OS != "win",
            'defines': [
              'NON_WINDOWS_DEFINE',
            ],
          }]
        ],
    ],
  }
```

--------------------------------

### Run GYP with Default Arguments

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/Testing.md

Execute a .gyp file using the run_gyp method. This is the canonical way to run GYP within a test.

```python
  test.run_gyp('file.gyp')
```

--------------------------------

### Run Arbitrary Executable

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/Testing.md

Execute any program, not necessarily built by GYP. The program must be in the current directory or an absolute path.

```python
  test.run('program')
```

--------------------------------

### Run Built Executable

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/Testing.md

Execute a program that was built by the GYP-generated configuration. Handles platform-specific suffixes and output locations.

```python
  test.run_built_executable('program')
```

--------------------------------

### Run GYP from a Subdirectory

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/Testing.md

Execute GYP from a specified subdirectory using the chdir argument in run_gyp.

```python
  test.run_gyp('file.gyp', chdir='subdir')
```

--------------------------------

### Running a Specific GYP Test Script

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/Testing.md

Demonstrates how to execute a single GYP test script using the `gyptest.py` runner, specifying the test script path.

```bash
  $ python gyptest.py test/hello/gyptest-all.py
PYTHONPATH=/home/knight/src/gyp/trunk/test/lib
TESTGYP_FORMAT=scons
/usr/bin/python test/hello/gyptest-all.py
PASSED
$

```

--------------------------------

### Define a New Library Target

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/UserDocumentation.md

Add this dictionary to the 'targets' list in your .gyp file to define a new library. It supports common build configurations like defines, include directories, dependencies, and sources.

```gyp
  {
    'targets': [
      {
        'target_name': 'new_library',
        'type': '<(library)',
        'defines': [
          'FOO',
          'BAR=some_value',
        ],
        'include_dirs': [
          '..',
        ],
        'dependencies': [
          'other_target_in_this_file',
          'other_gyp2:target_in_other_gyp2',
        ],
        'direct_dependent_settings': {
          'include_dirs': '.',
        },
        'export_dependent_settings': [
          'other_target_in_this_file',
        ],
        'sources': [
          'new_additional_source.cc',
          'new_library.cc',
        ],
      },
    ],
  }
```

--------------------------------

### Configuring Node-gyp nodedir with npm

Source: https://github.com/nodejs/node-gyp/blob/main/docs/Error-pre-versions-of-node-cannot-be-installed.md

To avoid repeatedly specifying the `--nodedir` flag, configure npm to use a default path for your Node.js source code directory.

```bash
$ npm config set nodedir /Users/nrajlich/node
```

--------------------------------

### Add a new executable target

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/UserDocumentation.md

Define a new executable target with its sources, dependencies, and include directories. This configuration applies across all platforms.

```gyp
{
    "targets": [
      {
        "target_name": "new_unit_tests",
        "type": "executable",
        "defines": [
          "FOO",
        ],
        "include_dirs": [
          "..",
        ],
        "dependencies": [
          "other_target_in_this_file",
          "other_gyp2:target_in_other_gyp2",
        ],
        "sources": [
          "new_additional_source.cc",
          "new_unit_tests.cc",
        ],
      },
    ],
  }
```

--------------------------------

### Define Custom Build Actions

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/LanguageSpecification.md

Use the 'actions' section to define custom build steps. The build system invokes these actions if outputs are missing or outdated relative to inputs. Specify Python-based actions with 'python' as the first element for cross-platform compatibility.

```python
      'sources': [
        # libraries.cc is generated by the js2c action below.
        '<(INTERMEDIATE_DIR)/libraries.cc',
      ],
      'actions': [
        {
          'variables': {
            'core_library_files': [
              'src/runtime.js',
              'src/v8natives.js',
              'src/macros.py',
            ],
          },
          'action_name': 'js2c',
          'inputs': [
            'tools/js2c.py',
            '<@(core_library_files)',
          ],
          'outputs': [
            '<(INTERMEDIATE_DIR)/libraries.cc',
            '<(INTERMEDIATE_DIR)/libraries-empty.cc',
          ],
          'action': ['python', 'tools/js2c.py', '<@(_outputs)', 'CORE', '<@(core_library_files)'],
        },
      ],

```

--------------------------------

### Run GYP with Additional Arguments

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/Testing.md

Pass additional command-line arguments to GYP when using the run_gyp method.

```python
  test.run_gyp('file.gyp', arguments=['arg1', 'arg2', ...])
```

--------------------------------

### Add Platform-Specific Source Files (Custom Conditions - Preferred)

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/UserDocumentation.md

For files not matching standard suffixes, add them to the 'sources' list and use 'conditions' to exclude them on unwanted platforms. This keeps a global list of all sources.

```python
  {
    'targets': [
      {
        'target_name': 'foo',
        'type': 'executable',
        'sources': [
          'linux_specific.cc',
        ],
        'conditions': [
          ['OS != "linux"', {
            'sources!': [
              # Linux-only; exclude on other platforms.
              'linux_specific.cc',
            ]
          }[,
        ],
      },
    ],
  },

```

--------------------------------

### Configure node-gyp with package.json

Source: https://github.com/nodejs/node-gyp/blob/main/README.md

Set node-gyp options directly in your package.json file using the 'config' object. Keys should follow the format 'node_gyp_OPTION_NAME'.

```json
{
  "config": {
    "node_gyp_devdir": "/tmp/.gyp"
  }
}
```

--------------------------------

### Add Platform-Specific Source Files (Standard Suffixes)

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/UserDocumentation.md

Include platform-specific source files by using standard naming conventions (e.g., `_linux`, `_win`). GYP automatically filters these based on the OS.

```python
  {
    'targets': [
      {
        'target_name': 'foo',
        'type': 'executable',
        'sources': [
          'independent.cc',
          'specific_win.cc',
        ],
      },
    ],
  },

```

--------------------------------

### Specify Node.js runtime headers for building modules

Source: https://github.com/nodejs/node-gyp/blob/main/README.md

Builds Node.js modules for third-party runtimes like Electron by specifying the runtime headers using --dist-url or --nodedir. The --force-process-config flag can be used to work around configuration errors in older Electron versions.

```bash
node-gyp --dist-url=https://electronjs.org/headers/vX.Y.Z
```

```bash
node-gyp --nodedir=/path/to/electron/headers
```

```bash
node-gyp --force-process-config
```

--------------------------------

### Running All GYP Tests in a Directory

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/Testing.md

Shows how to run all GYP test scripts within a specified directory using `gyptest.py`. The runner automatically discovers and executes scripts prefixed with `gyptest-`.

```bash
  $ python gyptest.py test/hello
PYTHONPATH=/home/knight/src/gyp/trunk/test/lib
TESTGYP_FORMAT=scons
/usr/bin/python test/hello/gyptest-all.py
PASSED
/usr/bin/python test/hello/gyptest-default.py
PASSED
/usr/bin/python test/hello/gyptest-target.py
PASSED
$

```

--------------------------------

### Configure Mac OS X Bundle Target

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/UserDocumentation.md

Define a target to build a Mac OS X bundle (.app, .framework, .bundle). Use 'mac_bundle': 1 to enable bundle creation and specify bundle resources and product name.

```python
    {
      'target_name': 'test_app',
      'product_name': 'Test App Gyp',
      'type': 'executable',
      'mac_bundle': 1,
      'sources': [
        'main.m',
        'TestAppAppDelegate.h',
        'TestAppAppDelegate.m',
      ],
      'mac_bundle_resources': [
        'TestApp/English.lproj/InfoPlist.strings',
        'TestApp/English.lproj/MainMenu.xib',
      ],
      'link_settings': {
        'libraries': [
          '$(SDKROOT)/System/Library/Frameworks/Cocoa.framework',
        ],
      },
      'xcode_settings': {
        'INFOPLIST_FILE': 'TestApp/TestApp-Info.plist',
      },
    },
```

--------------------------------

### Clone GYP Repository

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/Hacking.md

Clone the GYP repository to your local machine to begin development. Ensure you are in the desired parent directory before cloning.

```sh
mkdir foo
cd foo
git clone git@github.com:nodejs/gyp-next.git
cd gyp
```

--------------------------------

### Configure node-gyp with Environment Variables (Windows)

Source: https://github.com/nodejs/node-gyp/blob/main/README.md

Set node-gyp options using environment variables on Windows systems. Use the format 'npm_package_config_node_gyp_OPTION_NAME'.

```console
set npm_package_config_node_gyp_devdir=c:\temp\.gyp
```

--------------------------------

### Update node-gyp on Windows (npm < 7)

Source: https://github.com/nodejs/node-gyp/blob/main/docs/Updating-npm-bundled-node-gyp.md

For npm versions less than 7 on Windows, after navigating to the correct directory, run this command to update the bundled node-gyp. Ensure you are in an Administrator command prompt.

```bash
cd node_modules\npm\node_modules\npm-lifecycle
$ npm install node-gyp@latest
```

--------------------------------

### Verify File/Directory Non-Existence

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/Testing.md

Assert that a specified file or directory does not exist. Fails the test if it does.

```python
  test.must_not_exist('file_or_dir')
```

--------------------------------

### Configure node-gyp with Environment Variables (Unix)

Source: https://github.com/nodejs/node-gyp/blob/main/README.md

Set node-gyp options using environment variables on Unix-like systems. Use the format 'npm_package_config_node_gyp_OPTION_NAME'.

```bash
export npm_package_config_node_gyp_devdir=/tmp/.gyp
```

--------------------------------

### Specify Static Library Type

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/UserDocumentation.md

Hard-wire the 'type' field to 'static_library' if a specific library must be built as a static library.

```gyp
        'type': 'static_library',
```

--------------------------------

### Exclude Files from Sources Conditionally

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/InputFormatReference.md

Demonstrates how to conditionally exclude specific source files from a target based on operating system conditions using exclusion lists.

```python
{
  'sources:' [
    'mac_util.mm',
    'win_util.cc',
  ],
  'conditions': [
    ['OS=="mac"', {'sources!': ['win_util.cc']}],
    ['OS=="win"', {'sources!': ['mac_util.cc']}],
  ],
}
```

--------------------------------

### Verify File/Directory Existence

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/Testing.md

Assert that a specified file or directory exists. Fails the test if it does not.

```python
  test.must_exist('file_or_dir')
```

--------------------------------

### Configure node-gyp with npm config (versions before v9)

Source: https://github.com/nodejs/node-gyp/blob/main/README.md

For npm versions before v9, you can set node-gyp options using 'npm config set'. This configuration is only applied when node-gyp is invoked via npm.

```bash
npm config set [--global] devdir /tmp/.gyp
```

--------------------------------

### Verify Exact File Content Match

Source: https://github.com/nodejs/node-gyp/blob/main/gyp/docs/Testing.md

Use this to ensure a file's content exactly matches the expected string. Fails the test if there's any discrepancy.

```javascript
test.must_match('file', 'expected content\n')
```