### Example GitHub Actions Workflow with Nuitka-Action

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/execution-workflow.md

This workflow demonstrates a typical setup using Nuitka-Action to build a Python application. It includes checking out code, setting up Python, running Nuitka-Action, and uploading the resulting artifact.

```yaml
name: Build

on: push

jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.10"
      
      - uses: Nuitka/Nuitka-Action@main
        with:
          nuitka-version: main
          script-name: app.py
          mode: app
      
      - uses: actions/upload-artifact@v4
        with:
          name: ${{ runner.os }}
          path: build/
          include-hidden-files: true

```

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

### Python and Package Dependencies

Source: https://github.com/nuitka/nuitka-action/blob/main/README.rst

This example lists the Python packages that are installed by the Nuitka Action, as specified by its requirements.txt file.

```text
ordered-set==4.1.0
    # via -r requirements.in
wheel==0.38.4
    # via -r requirements.in
zstandard==0.20.0
```

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

### Install Dependencies

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/execution-workflow.md

Installs base requirements from requirements.txt and Nuitka from a Git repository. Uses a commercial repository if an access token is provided.

```bash
pip install -r "${{ github.action_path }}/requirements.txt"

# With commercial access token, use that repository.
if [ "${{ inputs.access-token }}" != "" ]; then
  repo_url="git+https://${{ inputs.access-token }}@github.com/Nuitka/Nuitka-commercial.git"
else
  repo_url="git+https://$@github.com/Nuitka/Nuitka.git"
fi

pip install "${repo_url}/@${{ inputs.nuitka-version }}#egg=nuitka"
```

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

### Create a Python Script

Source: https://github.com/nuitka/nuitka-action/blob/main/README.rst

Example of a basic Python script that prints 'hello world!'.

```python
## hello_world.py
print("hello world!")
```

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

### Setup Environment Variables

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/execution-workflow.md

Sets NUITKA_CACHE_DIR and PYTHON_VERSION environment variables. Runs only if caching is not disabled.

```bash
echo "NUITKA_CACHE_DIR=${{ github.action_path }}/nuitka/cache" >> $GITHUB_ENV
echo "PYTHON_VERSION=$(python --version | awk '{print $2}' | cut -d '.' -f 1,2)" >> $GITHUB_ENV
```

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

### Build GUI Application with PySide6

Source: https://github.com/nuitka/nuitka-action/blob/main/README.rst

This example demonstrates building a GUI application using PySide6. It requires enabling the 'pyside6' plugin for Nuitka.

```yaml
- name: Qt GUI with PySide6
  uses: Nuitka/Nuitka-Action@main
  with:
    nuitka-version: main
    script-name: my_qt_gui_app.py
    mode: standalone
    enable-plugins: pyside6
```

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

### Enable Clang C Compiler Backend

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/action-inputs.md

Use clang as the C compiler backend. This requires a working Visual Studio installation on Windows.

```yaml
with:
  clang: true
```

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

### Install ccache on Linux

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/execution-workflow.md

Installs the ccache package using apt-get. This step is specific to Linux environments and can be skipped by setting `disable-cache: ccache`.

```bash
sudo apt-get install -y ccache
```

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

### Build GUI Application with TkInter

Source: https://github.com/nuitka/nuitka-action/blob/main/README.rst

This example shows how to build a GUI application using TkInter. It requires enabling the 'tk-inter' plugin for Nuitka.

```yaml
- name: Python GUI With TkInter
  uses: Nuitka/Nuitka-Action@main
  with:
    nuitka-version: main
    script-name: my_tkinter_gui_app.py
    mode: standalone
    enable-plugins: tk-inter
```

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

### Multi-Platform Build Configuration

Source: https://github.com/nuitka/nuitka-action/blob/main/README.rst

This configuration sets up a matrix strategy to build executables for multiple platforms (macOS, Linux, Windows) within a single workflow. It includes Python setup, dependency installation, and artifact uploading.

```yaml
jobs:
  build:
    strategy:
      matrix:
        os: [macos-latest, ubuntu-latest, windows-latest]

    runs-on: ${{ matrix.os }}

    steps:
      - name: Check-out repository
        uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.10' # Version range or exact version of a Python version to use, using SemVer's version range syntax
          architecture: 'x64' # optional x64 or x86. Defaults to x64 if not specified
          cache: 'pip'
          cache-dependency-path: |
            **/requirements*.txt

      - name: Install Dependencies
        run: |
          pip install -r requirements.txt -r requirements-dev.txt

      - name: Build Executable
        uses: Nuitka/Nuitka-Action@main
        with:
          nuitka-version: main
          script-name: your_script.py
          mode: app

      - name: Upload Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: ${{ runner.os }} Build
          path: |
            build/*.exe
            build/*.bin
            build/*.app/**/*
            build/*.dist/**/*
          include-hidden-files: true
```

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

### Nuitka-Action Workflow Step

Source: https://github.com/nuitka/nuitka-action/blob/main/README.rst

Example of how to use Nuitka-Action as a step in a GitHub Actions CI workflow.

```yaml

```

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

### Enable DMG Installer Creation

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/action-inputs.md

Set this option to 'true' to automatically create a DMG installer for your macOS application bundle. This is useful for distributing your application.

```yaml
with:
  mode: app
  macos-app-create-dmg: true
```

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

### Production-Ready Nuitka-Action Workflow

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/configuration-guide.md

A comprehensive GitHub Actions workflow for building and releasing Python applications using Nuitka. This example includes matrix builds for cross-platform compatibility, metadata configuration, caching, and release automation.

```yaml
name: Build and Release

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    strategy:
      matrix:
        include:
          - os: windows-latest
            python-version: "3.10"
          - os: ubuntu-latest
            python-version: "3.10"
          - os: macos-latest
            python-version: "3.10"
            macos-target-arch: arm64
    
    runs-on: ${{ matrix.os }}
    
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
      
      - name: Install dependencies
        run: pip install -r requirements.txt
      
      - uses: Nuitka/Nuitka-Action@main
        with:
          nuitka-version: stable
          script-name: myapp.py
          mode: app
          
          # Metadata
          company-name: "My Company"
          product-name: "MyApp"
          file-version: ${{ github.ref_name }}
          product-version: ${{ github.ref_name }}
          
          # Platform-specific
          windows-icon-from-ico: ./assets/icon.ico
          macos-app-icon: ./assets/icon.icns
          macos-app-version: ${{ github.ref_name }}
          macos-target-arch: ${{ matrix.macos-target-arch || 'native' }}
          
          # Build options
          lto: yes
          reproducible: yes
          
          # Output
          output-dir: ./dist
      
      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: ${{ runner.os }}-${{ matrix.python-version }}
          path: dist/
          include-hidden-files: true
      
      - name: Create Release
        if: startsWith(github.ref, 'refs/tags/')
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{ github.ref_name }}
          release_name: Release ${{ github.ref_name }}
          draft: false
          prerelease: false
```

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

### Nuitka Action Environment Context

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/execution-workflow.md

Details the environment variables and installed tools available during the Nuitka compilation step (Step 5), crucial for understanding build conditions.

```text
GitHub Actions Variables:
- GITHUB_ACTION_PATH — Absolute path to action directory
- GITHUB_SHA — Current commit SHA
- GITHUB_REF — Git reference (branch/tag)
- GITHUB_WORKSPACE — Repository root

Action-Set Variables (from Step 1):
- NUITKA_CACHE_DIR — Cache directory path
- PYTHON_VERSION — Detected Python major.minor

Build Environment (Step 5):
- PYTHONUTF8=1 — UTF-8 encoding enabled
- NUITKA_WORKFLOW_INPUTS — Serialized JSON inputs
- PWD — Working directory (${{ inputs.working-directory }})

Installed Tools:
- Python interpreter
- pip package manager
- Nuitka compiler
- Required dependencies (ordered-set, wheel, zstandard)
- C compiler (MSVC, gcc, clang, Zig depending on platform)
- ccache (Linux only, if enabled)
```

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

### Install Dependencies for Nuitka Build

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/configuration-guide.md

Install Python dependencies before running the Nuitka build. This is crucial for resolving 'Module not found' errors.

```yaml
name: Install dependencies
run: pip install -r requirements.txt
```

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

### Nuitka Cache Key for Windows Runner

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/execution-workflow.md

Example cache key format for a Windows x64 runner using Python 3.10 and Nuitka.

```text
nuitka-caching-Windows-X64-python-3.10-nuitka-{sha}
```

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

### Nuitka Cache Key for Linux Runner

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/execution-workflow.md

Example cache key format for a Linux x64 runner using Python 3.10 and Nuitka.

```text
nuitka-caching-Linux-X64-python-3.10-nuitka-{sha}
```

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

### Build GUI Application with PySide6 and Nuitka-Action

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/configuration-guide.md

Configure Nuitka-Action to build GUI applications using PySide6. Ensure PySide6 is installed in the runner environment and specify the plugin and any data directories to include.

```yaml
- uses: Nuitka/Nuitka-Action@main
  with:
    script-name: gui_app.py
    mode: standalone
    enable-plugins: pyside6
    include-data-dir: ./resources=resources
```

```yaml
- name: Install dependencies
  run: pip install PySide6
```

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

### Specify MSVC Version for C Compilation

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/action-inputs.md

Use a specific MSVC version for C compilation on Windows. Examples include '14.3' for MSVC 2022 or '14.2' for MSVC 2019. Use 'list' to display installed versions.

```yaml
with:
  msvc: "14.3"
```

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

### Handle Dependencies Before Compilation

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/configuration-guide.md

Install project dependencies using `pip` before invoking Nuitka-Action. This ensures Nuitka can analyze imports correctly during the compilation process.

```yaml
# GOOD: Install deps before Nuitka-Action
- name: Install dependencies
  run: pip install -r requirements.txt

- uses: Nuitka/Nuitka-Action@main
  with:
    script-name: app.py
    enable-plugins: pyside6
```

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

### Basic Nuitka-Action Usage

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/configuration-guide.md

Basic usage of Nuitka-Action to compile a Python script. This is a starting point for most builds.

```yaml
uses: Nuitka/Nuitka-Action@main
with:
  script-name: app.py
```

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

### Nuitka Cache Key for macOS Runner

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/execution-workflow.md

Example cache key format for a macOS ARM64 runner using Python 3.11 and Nuitka.

```text
nuitka-caching-macOS-ARM64-python-3.11-nuitka-{sha}
```

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

### Initialize and get Nuitka option parser

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/update-script-api.md

Lazily initializes and returns Nuitka's option parser with all plugin options loaded. Caches the result for subsequent calls.

```python
parser = _getParser()
for option in parser.iterateOptions():
    print(option)
```

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

### Nuitka-Action with Standalone Mode

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/configuration-guide.md

Configure Nuitka-Action to build a standalone executable, ensuring all dependencies are bundled. Use this when the executable needs to run on machines without Python installed.

```yaml
uses: Nuitka/Nuitka-Action@main
with:
  script-name: app.py
  mode: standalone
```

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

### Provide Access Token for Commercial Nuitka

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/action-inputs.md

If you have a commercial license, use the 'access-token' input with your GitHub Personal Access Token (PAT). This token must have access to the private 'Nuitka/Nuitka-commercial' repository and enables installation from the commercial repository.

```yaml
- uses: Nuitka/Nuitka-Action@main
  with:
    access-token: ${{ secrets.NUITKA_COMMERCIAL_TOKEN }}
    script-name: app.py
```

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

### Run Python Script

Source: https://github.com/nuitka/nuitka-action/blob/main/README.rst

Demonstrates how to run a Python script from the command line.

```console
C:\> python hello_world.py
hello world!
```

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

### Platform Output Structure - Windows

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/README.md

Illustrates the typical output directory structure for Nuitka builds on Windows, including the main executable and optional standalone distribution folder.

```bash
build/
├── app.exe              # Main executable
├── app.dist/ (if standalone)
│   ├── dependencies.dll
│   └── ...

```

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

### Nuitka Action: Show SCons Backend Details

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/action-inputs.md

Enable 'show-scons' to display details about the SCons C compilation backend, including executed commands and detected compilers.

```yaml
with:
  show-scons: true
```

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

### Nuitka Action File Manifest Summary

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/MANIFEST.md

Lists the main documentation files generated for the nuitka-action project and their approximate line counts. These files cover various aspects of the action, from inputs to execution details.

```bash
# Analysis performed on these source files:
# - action.yml (689 lines)
# - action.yml.j2 (175 lines)
# - update-from-nuitka-options.py (228 lines)
# - README.rst (313 lines)
# - requirements.txt (13 lines)
# - requirements-dev.txt (1 line)
# - .vscode/settings.json (minimal)

# Documentation generated without use of external tools,
# based on careful reading and categorization of source code
```

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

### Local Testing Commands for Nuitka

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/configuration-guide.md

Before committing, verify Nuitka syntax with `--help`, test the original script, the compilation process, and the final compiled output locally.

```bash
# Run locally before committing
python -m nuitka --help  # Verify syntax
python app.py  # Test original script
python -m nuitka app.py  # Test compilation
./app.bin  # Test compiled output
```

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

### Nuitka Action Project Configuration: project '.'

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/action-inputs.md

Enables compilation using project configuration from a file like pyproject.toml. Specify '.' to use configuration from the current directory.

```yaml
with:
  project: "."
  script-name: app.py
```

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

### Cross-Platform Nuitka-Action Build Matrix

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/README.md

Set up a build matrix to run the Nuitka-Action on multiple operating systems (Ubuntu, Windows, macOS) for cross-platform compatibility.

```yaml
strategy:
  matrix:
    os: [ubuntu-latest, windows-latest, macos-latest]
runs-on: ${{ matrix.os }}
steps:
  - uses: Nuitka/Nuitka-Action@main
    with:
      script-name: app.py
      mode: app
```

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

### Nuitka-Action for GUI Application

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/README.md

Build a GUI application by specifying the script name, standalone mode, enabling relevant plugins (e.g., pyside6), and including data directories.

```yaml
- uses: Nuitka/Nuitka-Action@main
  with:
    script-name: gui_app.py
    mode: standalone
    enable-plugins: pyside6
    include-data-dir: ./resources=resources
```

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

### Basic Executable Build with Nuitka Action

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/overview.md

Use this configuration to build a basic Python application into an executable. Specify the script name and the desired mode.

```yaml
- uses: Nuitka/Nuitka-Action@main
  with:
    nuitka-version: main
    script-name: my_app.py
    mode: app
```

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

### Use Proper Output Directory Structure

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/configuration-guide.md

Organize build artifacts by platform and Python version for clarity. This helps in managing different build outputs effectively.

```yaml
# GOOD: Separate builds by platform
- uses: actions/upload-artifact@v4
  with:
    name: ${{ runner.os }}-${{ matrix.python-version }}
    path: build/
    include-hidden-files: true
```

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

### Disable Specific Deployment Features

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/action-inputs.md

Use `no-deployment-flag` to selectively disable parts of deployment mode using error identifiers. For example, disable the `module-not-installed-check`.

```yaml
with:
  no-deployment-flag: "module-not-installed-check"
```

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

### Use Custom Cache Key

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/configuration-guide.md

Specify a custom cache key to ensure build independence, for example, when dealing with multiple build variants or specific configurations.

```yaml
- uses: Nuitka/Nuitka-Action@main
  with:
    script-name: app.py
    caching-key: "custom-build-v2"
```

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

### Build Simple Executable with Nuitka-Action

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/configuration-guide.md

Use this configuration to convert a Python script into a standalone executable. Specify the entry point script name and the desired mode.

```yaml
name: Build Executable
on: push
jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [windows-latest, ubuntu-latest, macos-latest]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.10"
      
      - uses: Nuitka/Nuitka-Action@main
        with:
          script-name: hello.py
          mode: app
```

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

### Nuitka-Action for GUI Frameworks

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/configuration-guide.md

Enable specific plugins for GUI frameworks like PySide6 to ensure correct bundling. Add the relevant plugin name to 'enable-plugins'.

```yaml
uses: Nuitka/Nuitka-Action@main
with:
  script-name: gui_app.py
  enable-plugins: pyside6
  mode: standalone
```

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

### Get top-level Nuitka options

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/update-script-api.md

Yields top-level Nuitka options that are not part of any specific option group. These are options directly associated with the main parser instance.

```python
for option in getTopOptions():
    print(f"Top-level: {option._long_opts[0]}")
```

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

### Set Product Version for Executable Resources

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/action-inputs.md

Define the product version for the executable's resources, using the same dot-separated number format as `file-version`. This input is also Windows-specific.

```yaml
with:
  product-version: "2.1.0.0"
```

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

### Production Nuitka-Action Build with Caching

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/README.md

Configure a production build with Nuitka version, standalone mode, output directory, and a specific caching key for improved performance.

```yaml
- uses: Nuitka/Nuitka-Action@main
  with:
    nuitka-version: stable
    script-name: app.py
    mode: standalone
    output-dir: dist
    caching-key: "prod-v1"
```

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

### Run Executable

Source: https://github.com/nuitka/nuitka-action/blob/main/README.rst

This snippet shows how to run the compiled executable from the command line after it has been built.

```console
C:\> hello_world.exe
hello world!
```

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

### Manual Cache Invalidation Example

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/execution-workflow.md

To manually invalidate the cache, increment the 'caching-key' input when using the Nuitka/Nuitka-Action. This ensures that new cache keys are generated, effectively ignoring older caches.

```yaml
- uses: Nuitka/Nuitka-Action@main
  with:
    caching-key: "v2"  # Changed from default "caching"

```

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

### Nuitka Action: Auto-Download Dependencies

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/action-inputs.md

Set 'assume-yes-for-downloads' to true to allow Nuitka to automatically download external tools like dependency walker, ccache, or gcc on Windows. The default is true.

```yaml
with:
  assume-yes-for-downloads: true
```

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

### Get Nuitka options by group name

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/update-script-api.md

Yields Nuitka options belonging to a specific option group, identified by its exact title. Useful for retrieving options related to a particular feature set.

```python
for option in getGroupOptions("Plugin control"):
    print(option._long_opts[0])
```

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

### Get filtered Nuitka options for GitHub Actions

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/update-script-api.md

Yields Option objects that should be exposed in the GitHub Action, filtering by metadata flags. Excludes help and main options, and requires compilation-related and github_action attributes.

```python
for option in getOptions():
    print(f"{option._long_opts[0]}: {option.help}")
```

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

### Multi-Platform Build Matrix with Nuitka-Action

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/configuration-guide.md

Set up a GitHub Actions workflow to build your application for multiple operating systems and Python versions simultaneously using a matrix strategy. Artifacts are uploaded with names specific to each build variant.

```yaml
name: Multi-Platform Build
on: push

jobs:
  build:
    strategy:
      matrix:
        include:
          - os: windows-latest
            python-version: "3.10"
          - os: ubuntu-latest
            python-version: "3.11"
          - os: macos-latest
            python-version: "3.12"
    
    runs-on: ${{ matrix.os }}
    
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
      
      - uses: Nuitka/Nuitka-Action@main
        with:
          script-name: app.py
          mode: app
      
      - uses: actions/upload-artifact@v4
        with:
          name: ${{ runner.os }}-py${{ matrix.python-version }}
          path: build/
          include-hidden-files: true
```

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

### Monitor Build Times and Cache Effectiveness

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/configuration-guide.md

Monitor build performance by checking cache size and output verification. Use commands like `du -sh` for cache size and `ls -la` for output inspection.

```yaml
- uses: Nuitka/Nuitka-Action@main
  with:
    script-name: app.py
    show-memory: true

- name: Check cache stats
  run: |
    du -sh nuitka/cache/  # Cache size
    ls -la build/         # Output verification
```

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

### Nuitka-Action with Caching and Job Limits

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/configuration-guide.md

Optimize build times by managing the cache and limiting parallel jobs. Set 'disable-cache' to 'false' to ensure caching is enabled. Adjust 'jobs' to control concurrency.

```yaml
uses: Nuitka/Nuitka-Action@main
with:
  script-name: app.py
  disable-cache: false
  jobs: "4"
```

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

### Enable Deployment Mode

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/action-inputs.md

Set `deployment` to `true` to disable compatibility troubleshooting code for production deployments. This is recommended when deploying to end users.

```yaml
with:
  deployment: true
```

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

### GUI Application Build with PySide6 Plugin

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/overview.md

Build a GUI application using PySide6. Enable the 'pyside6' plugin and set the mode to 'standalone' for a self-contained executable.

```yaml
- uses: Nuitka/Nuitka-Action@main
  with:
    nuitka-version: main
    script-name: my_gui.py
    mode: standalone
    enable-plugins: pyside6
```

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

### update-from-nuitka-options.py

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/update-script-api.md

The main entry point for the script. It is designed to be run from the repository root to update the `action.yml` file based on Nuitka's command-line options.

```APIDOC
## Script Execution

### Description

This script automatically regenerates `action.yml` from Nuitka's command-line option definitions to ensure GitHub Actions inputs stay synchronized with Nuitka's evolving option set.

### Command

```bash
python update-from-nuitka-options.py
```

### Output

Updates `action.yml` if changes are detected. Prints a status message indicating the outcome.
```

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

### Platform Output Structure - Linux

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/README.md

Shows the expected output directory layout for Nuitka builds on Linux, featuring the main executable and a directory for shared libraries.

```bash
build/
├── app.bin              # Main executable
├── app.libs/            # Shared libraries
│   └── libname.so.6

```

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

### Minimal Nuitka-Action Build

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/README.md

This is the most basic configuration for the Nuitka-Action, specifying only the script name to be compiled.

```yaml
- uses: Nuitka/Nuitka-Action@main
  with:
    script-name: app.py
```

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

### Commercial Features and Code Signing with Nuitka-Action

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/configuration-guide.md

Configure Nuitka-Action to build and sign executables for distribution, including options for Windows and macOS code signing. Ensure you have a commercial Nuitka license and your signing certificates are stored as GitHub Secrets.

```yaml
- uses: Nuitka/Nuitka-Action@main
  with:
    access-token: ${{ secrets.NUITKA_COMMERCIAL_TOKEN }}
    script-name: app.py
    mode: onefile
    
    # Windows signing
    windows-certificate-filename: ${{ secrets.CERT_FILE }}
    windows-certificate-password: ${{ secrets.CERT_PASSWORD }}
    windows-certificate-sha1: ${{ secrets.CERT_SHA1 }}
    
    # macOS signing
    macos-sign-identity: "Developer ID Application: My Company (ABCD1234)"
    macos-sign-notarization: true
```

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

### Configure Development vs. Release Builds

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/configuration-guide.md

Set build mode, output verbosity, debug flags, and caching keys based on the Git branch. Use 'app' mode and full output for release on 'main', and 'accelerated' mode with quiet output and debug enabled for development on 'develop'.

```yaml
name: Build

on:
  push:
    branches: [main, develop]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.10"
      
      - uses: Nuitka/Nuitka-Action@main
        with:
          script-name: app.py
          mode: ${{ github.ref == 'refs/heads/main' && 'app' || 'accelerated' }}
          quiet: ${{ github.ref == 'refs/heads/main' && 'false' || 'true' }}
          debug: ${{ github.ref != 'refs/heads/main' && 'true' || 'false' }}
          caching-key: ${{ github.ref == 'refs/heads/main' && 'release' || 'dev' }}
```

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

### User Package Configuration File Input for Nuitka Action

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/action-inputs.md

Specify the path to a YAML file containing package-specific configurations for controlling DLLs, removing bloat, or adding hidden dependencies. This can be specified multiple times.

```yaml
with:
  user-package-configuration-file: |
    ./nuitka-package.yaml
    ./nuitka-overrides.yaml
```

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

### Run update-from-nuitka-options.py script

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/update-script-api.md

Execute the script from the repository root to update action.yml. The script synchronizes GitHub Actions inputs with Nuitka compiler options.

```bash
python update-from-nuitka-options.py
```

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

### Set Product Name for Version Information

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/action-inputs.md

Specify the product name for the version information in the executable's resources. If not provided, it defaults to the base filename of the executable.

```yaml
with:
  product-name: "MyApp"
```

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

### Run Nuitka Update Script

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/update-script-api.md

Execute the script from the repository root to update Nuitka-related configurations.

```bash
# From repository root
python update-from-nuitka-options.py
```

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

### Platform Output Structure - macOS

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/README.md

Details the output structure for Nuitka builds on macOS, including the app bundle, standalone executable, and dependency directory.

```bash
build/
├── app.app/             # App bundle
├── app.bin              # Standalone executable
└── app.libs/            # Dependencies

```

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

### Set File Description for Executable

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/action-inputs.md

Use this input to set a description for the compiled executable. This is specific to Windows and defaults to the executable's filename if not provided.

```yaml
with:
  file-description: "A cool application"
```

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

### Set File Version for Executable Resources

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/action-inputs.md

Provide a file version string for the executable's resources. This input is Windows-specific and must follow a format of 1-4 dot-separated numbers (e.g., `1.0` or `1.0.0.0`).

```yaml
with:
  file-version: "1.2.3.0"
```

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

### Bundle Data Files and Resources with Nuitka-Action

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/configuration-guide.md

Specify data files and directories to be included in your application bundle. This configuration allows you to bundle assets, configuration files, and other resources alongside your executable. You can also exclude unwanted files.

```yaml
- uses: Nuitka/Nuitka-Action@main
  with:
    script-name: app.py
    mode: standalone
    
    # Include entire directories
    include-data-dir: |
      ./assets=assets
      ./config=config
      ./templates=templates
    
    # Include specific file patterns
    include-data-files: |
      ./docs/*.md=docs/
      ./LICENSE=
    
    # Exclude unwanted files
    noinclude-data-files: |
      *.pyc
      __pycache__
      *.log
```

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

### get_plugin_options

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/update-script-api.md

Renders all plugin-specific options, organized by plugin group. It excludes Nuitka VM plugins and formats the output with group titles and indented options.

```APIDOC
## get_plugin_options() -> str

### Description
Renders all plugin-specific options organized by plugin group.

### Returns
`str` — YAML with plugin options grouped by plugin name

### Processing Steps
1. Collects all plugin option groups by checking container titles.
2. Filters out Nuitka VM plugins (pelock, themida).
3. Groups options by `container.title`.
4. For each group, outputs a title comment, then formatted options.
5. Indents the entire result by 2 spaces.

### Output Structure Example
```yaml
  ### Plugin options of 'plugin-name' (categories: ...) ###
  option-name:
    description: |
      Option description
```
```

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

### Enable Reproducible Builds

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/action-inputs.md

Enable reproducible builds. Valid values are 'yes', 'no', or 'auto'. Defaults to 'auto' (yes on Linux/macOS, no on Windows).

```yaml
with:
  reproducible: "yes"
```

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

### getOptions

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/update-script-api.md

Yields all Nuitka options that are intended to be exposed as GitHub Action inputs, filtering based on specific metadata.

```APIDOC
## `getOptions()`

### Description

Yields `Option` objects that are suitable for exposure as GitHub Action inputs. This function filters Nuitka's extensive option list based on criteria such as requiring compilation relevance and having the `github_action` flag set to `True`.

### Yields

- **Option** - An `Option` object that meets the filtering criteria.

### Filter Criteria

- Excludes `--help` option.
- Excludes `--main` option.
- Requires the `require_compiling` attribute to be present.
- Requires the `github_action` attribute to be set to `True`.
- Excludes options with the `SUPPRESS_HELP` flag.

### Example

```python
for option in getOptions():
    print(f"{option._long_opts[0]}: {option.help}")
```
```

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

### Nuitka Action: Display Memory Usage

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/action-inputs.md

Use 'show-memory' to display memory usage information and statistics during the compilation process.

```yaml
with:
  show-memory: true
```

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

### Specify Windows Executable Icon from ICO

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/action-inputs.md

Use `windows-icon-from-ico` to set the executable's icon using one or more ICO files. You can specify an icon index using `#n`.

```yaml
with:
  windows-icon-from-ico: ./assets/icon.ico
```

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

### Include Data Directories in Nuitka Build

Source: https://github.com/nuitka/nuitka-action/blob/main/README.rst

Configure multiple data directories to be included in the Nuitka build by specifying source-destination path pairs, separated by newlines.

```yaml
include-data-dir: |
  source_path_dir1=dest_path_dir1
  source_path_dir2=dest_path_dir2
  source_path_dir3=dest_path_dir3
```

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

### Prepare and Export Nuitka Workflow Inputs

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/execution-workflow.md

This script prepares Nuitka compilation options by filtering GitHub Actions specific inputs from the `toJson(inputs)` context and exporting them as an environment variable. It ensures only valid Nuitka arguments are passed, avoiding shell escaping issues.

```bash
set -e

# Prepare the JSON string for Nuitka, filtering out action-specific keys using Python
NUITKA_WORKFLOW_INPUTS=$(echo '${{ toJson(inputs) }}' | python -c "import sys, json; data = json.load(sys.stdin); [data.pop(k, None) for k in ['nuitka-version', 'working-directory', 'access-token', 'disable-cache', 'caching-key']]; json.dump(data, sys.stdout, ensure_ascii=False)")

# Pass the filtered JSON to Nuitka via an environment variable
export NUITKA_WORKFLOW_INPUTS
python -m nuitka --github-workflow-options
```

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

### Include Plugin Directory Input for Nuitka Action

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/action-inputs.md

Include the entire content of a directory unconditionally, overriding other inclusion options. This can be specified multiple times.

```yaml
with:
  include-plugin-directory: |
    ./plugins/
    ./extensions/
```

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

### Control Windows Console Mode

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/action-inputs.md

Configure the console behavior on Windows using `windows-console-mode`. Options include forcing a console, disabling it entirely, attaching to an existing one, or hiding a newly spawned console.

```yaml
with:
  windows-console-mode: "disable"
```

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

### Include Package Input for Nuitka Action

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/action-inputs.md

Use this input to include an entire Python package and all its modules recursively. Specify the full Python namespace.

```yaml
with:
  include-package: my_library
```

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

### Configure macOS Protected Resource Entitlements

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/action-inputs.md

Request specific entitlements for macOS protected resources. The format is 'NSIdentifier:Descriptive Text' for each entitlement you need, such as microphone or camera access.

```yaml
with:
  macos-app-protected-resource: |
    NSMicrophoneUsageDescription:This app needs microphone access
    NSCameraUsageDescription:Camera access for recording
```

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

### Enable Reproducible Builds for Releases

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/configuration-guide.md

Set `reproducible: yes` and serialize jobs using `jobs: "1"` for release builds. This ensures consistency and allows for verification and security audits.

```yaml
- uses: Nuitka/Nuitka-Action@main
  with:
    script-name: app.py
    mode: app
    reproducible: yes
    jobs: "1"  # Serialize for consistency
```

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

### Execute Nuitka with Workflow Options

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/execution-workflow.md

Runs Nuitka, instructing it to read compilation options from the `NUITKA_WORKFLOW_INPUTS` environment variable. This method is used to pass complex or numerous options without shell escaping issues.

```bash
python -m nuitka --github-workflow-options
```

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

### Resolve GitHub Action Reference

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/update-script-api.md

Demonstrates how the script resolves and pins GitHub Action references in action.yml.j2 templates.

```yaml
# In action.yml.j2, line 152:
{% endraw %}      uses: {{ resolve_action_ref('actions/cache@v5') }}
{% raw %}
# Becomes:
      uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
```

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

### Export Nuitka Options Environment Variable

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/execution-workflow.md

Makes the prepared JSON string of Nuitka options available to child processes via an environment variable.

```bash
export NUITKA_WORKFLOW_INPUTS
```

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

### Include Raw Directory

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/action-inputs.md

Use this input to include raw directories without processing. This is useful for including complete directory structures as-is, unlike `include-data-dir` which processes content.

```yaml
with:
  include-raw-dir: ./raw_assets=assets
```

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

### Configure Linux Icon for Onefile Executable

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/action-inputs.md

Specify an icon file for a onefile executable on Linux. This option is Linux-specific.

```yaml
with:
  linux-icon: ./assets/icon.png
```

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

### Provide Module-Specific Parameters

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/action-inputs.md

Use the 'module-parameter' input to pass module-specific parameters for packages that require them. The format is '--module-parameter=module.name-option-name=value'.

```yaml
with:
  module-parameter: mymodule-some-option=value
```

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

### Build with Commercial Features

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/overview.md

Utilize commercial features by providing a valid Nuitka commercial access token. This is required for accessing proprietary features.

```yaml
- uses: Nuitka/Nuitka-Action@main
  with:
    nuitka-version: main
    script-name: app.py
    access-token: ${{ secrets.NUITKA_COMMERCIAL_TOKEN }}
    mode: app
    # Plus any commercial-only options
```

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

### Set Onefile Splash Screen Image on Windows

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/action-inputs.md

Provide a splash screen image for the onefile executable during extraction and loading on Windows using `onefile-windows-splash-screen-image`.

```yaml
with:
  mode: onefile
  onefile-windows-splash-screen-image: ./splash.png
```

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

### Include Plugin Files Input for Nuitka Action

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/action-inputs.md

Include files matching glob patterns unconditionally, overriding other follow options. This can be specified multiple times.

```yaml
with:
  include-plugin-files: "*.so"
```

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

### Verify Python Version Output

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/execution-workflow.md

This command helps diagnose cache misses related to Python version detection. Ensure the output format is consistent and includes the version number.

```bash
python --version  # Should output: Python X.Y.Z

```

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

### Build Python Script into Executable

Source: https://github.com/nuitka/nuitka-action/blob/main/README.rst

This snippet shows how to use the Nuitka Action to build a Python script into a standalone executable. It specifies the Nuitka version and the script name.

```yaml
jobs:

  build:
    runs-on: windows-latest

    steps:

      # Check-out repository
      - uses: actions/checkout@v4

      # Setup Python
      - uses: actions/setup-python@v5
        with:
          python-version: '3.x' # Version range or exact version of a Python version to use, using SemVer's version range syntax
          architecture: 'x64' # optional x64 or x86. Defaults to x64 if not specified

      # Build python script into a single execute or app folder (macOS)
      - uses: Nuitka/Nuitka-Action@main
        with:
          nuitka-version: main
          script-name: hello_world.py
          mode: app

      # Uploads artifact
      - name: Upload Artifact
        uses: actions/upload-artifact@v4
        with:
          name: exe
          path: build/hello_world.exe
          include-hidden-files: true
```

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

### Nuitka Compiled Output Artifacts - Windows

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/execution-workflow.md

Shows the typical structure of compiled artifacts on Windows after a successful Nuitka compilation, including the executable and its dependencies.

```text
build/
├── app.exe              (executable)
├── app.pyd              (module, if module mode)
└── app.dist/
    ├── dependencies.dll
    └── ...
```

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

### Configure Static Python Library Linking

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/action-inputs.md

Configure whether to statically link the Python library. Valid values are 'yes', 'no', or 'auto'. Defaults to 'auto'.

```yaml
with:
  static-libpython: "yes"
```

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

### Nuitka-Action for macOS App Signing

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/configuration-guide.md

Configure macOS app signing for proper permissions. Set 'macos-sign-identity' to 'auto' for automatic detection.

```yaml
uses: Nuitka/Nuitka-Action@main
with:
  script-name: app.py
  mode: app
  macos-sign-identity: auto
```

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

### Render Action YAML and Update File

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/update-script-api.md

Renders the Jinja2 template with provided functions and updates the action.yml file if content has changed. Prints status messages.

```python
action_yaml = template.render(
    get_top_options=get_top_options,
    get_group_options=get_group_options,
    get_plugin_options=get_plugin_options,
    resolve_action_ref=resolve_action_ref,
)

if changeTextFileContents("action.yml", action_yaml):
    print("Updated.")
else:
    print("Already up to date.")
```

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

### Enable Multiple Plugins

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/action-inputs.md

To enable multiple Nuitka plugins, use a comma-separated list or a newline-separated block for the 'enable-plugins' input. This allows for enabling support for several libraries or features simultaneously.

```yaml
with:
  enable-plugins: |
    pyside6
    numpy
```

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

### Multiline Input Syntax for Nuitka Action

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/overview.md

Use newline-separated lists for options that accept multiple values in Nuitka, such as include-data-dir.

```yaml
with:
  include-data-dir: |
    source_path_dir1=dest_path_dir1
    source_path_dir2=dest_path_dir2
    source_path_dir3=dest_path_dir3
```

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

### Include Module Input for Nuitka Action

Source: https://github.com/nuitka/nuitka-action/blob/main/_autodocs/action-inputs.md

Use this input to include specific Python modules. Specify the full Python namespace.

```yaml
with:
  include-module: my_library.utilities
```