action.yml

# yamllint disable rule:line-length
# yamllint disable rule:comments
# too many spelling things, spell-checker: disable
---
name: Build executables or extension modules from Python projects

branding:
  icon: "package"
  color: "blue"

description: "Build a modules or standalone executable from python code using Nuitka on Mac/Linux/Windows. Very wide range of compatibility."

inputs:
  working-directory:
    default: "."
    description: "Directory to run nuitka in if not top level"

  nuitka-version:
    default: "main"
    description: "Version of nuitka to use, branches, tags work"

  ### Only Required Input ###
  script-name:
    required: true
    description: "Path to python script that is to be built."

  # Enable Nuitka Commercial features of Nuitka using a PAT (personal access token)
  access-token:
    description: "Github personal access token of an account authorized to access the Nuitka-commercial repo"

  ### Nuitka Modes ###
  module:
    description: |
      Create an importable binary extension module executable instead of a program. Defaults to off.
  mode:
    description: |
      Mode in which to compile. Accelerated runs in your Python
      installation and depends on it. Standalone creates a folder
      with an executable contained to run it. Onefile creates a
      single executable to deploy. Default is 'accelerated'.
    default: onefile
  standalone:
    description: |
      Enable standalone mode for output. This allows you to transfer the created binary
      to other machines without it using an existing Python installation. This also
      means it will become big. It implies these option: "--follow-imports" and
      "--python-flag=no_site". Defaults to off.
  onefile:
    description: |
      On top of standalone mode, enable onefile mode. This means not a folder,
      but a compressed executable is created and used. Defaults to off.
  python-flag:
    description: |
      Python flags to use. Default is what you are using to run Nuitka, this
      enforces a specific mode. These are options that also exist to standard
      Python executable. Currently supported: "-S" (alias "no_site"),
      "static_hashes" (do not use hash randomization), "no_warnings" (do not
      give Python run time warnings), "-O" (alias "no_asserts"), "no_docstrings"
      (do not use doc strings), "-u" (alias "unbuffered"), "isolated" (do not
      load outside code) and "-m" (package mode, compile as "package.__main__").
      Default empty.
  python-debug:
    description: |
      Use debug version or not. Default uses what you are using to run Nuitka, most
      likely a non-debug version. Only for debugging and testing purposes.

  ### Nuitka Plugins to enable. ###
  enable-plugins:
    description: |
      Enabled plugins. Must be plug-in names. Use '--plugin-list' to query the
      full list and exit. Default empty.
  user-plugin:
    description: |
      The file name of user plugin. Can be given multiple times. Default empty.
  plugin-no-detection:
    description: |
      Plugins can detect if they might be used, and the you can disable the warning
      via "--disable-plugin=plugin-that-warned", or you can use this option to disable
      the mechanism entirely, which also speeds up compilation slightly of course as
      this detection code is run in vain once you are certain of which plugins to
      use. Defaults to off.
  module-parameter:
    description: |
      Provide a module parameter. You are asked by some packages
      to provide extra decisions. Format is currently
      --module-parameter=module.name-option-name=value
      Default empty.

  ### Include Qt Plugins. ###
  include-qt-plugins:
    description: "A comma separated list of Qt plugins, such as qml, etc."
  noinclude-qt-plugins:
    description: "A comma separated list of Qt plugins to not included, to take away from default."

  ### Nuitka Tracing/Reporting features
  report:
    description: |
      Report module, data files, compilation, plugin, etc. details in an XML output file. This
      is also super useful for issue reporting. These reports can e.g. be used to re-create
      the environment easily using it with '--create-environment-from-report', but contain a
      lot of information. Default is off.
  report-diffable:
    description: |
      Report data in diffable form, i.e. no timing or memory usage values that vary from run
      to run. Default is off.
  report-user-provided:
    description: |
      Report data from you. This can be given multiple times and be
      anything in 'key=value' form, where key should be an identifier, e.g. use
      '--report-user-provided=pipenv-lock-hash=64a5e4' to track some input values.
      Default is empty.
  report-template:
    description: |
      Report via template. Provide template and output filename 'template.rst.j2:output.rst'. For
      built-in templates, check the User Manual for what these are. Can be given multiple times.
      Default is empty.
  quiet:
    description: |
      Disable all information outputs, but show warnings.
      Defaults to off.
  show-scons:
    description: |
      Run the C building backend Scons with verbose information, showing the executed commands,
      detected compilers. Defaults to off.
  show-memory:
    description: |
      Provide memory information and statistics.
      Defaults to off.

  ### Control the inclusion of data files in result. ###
  include-package-data:
    description: |
      Include data files for the given package name. DLLs and extension modules
      are not data files and never included like this. Can use patterns the
      filenames as indicated below. Data files of packages are not included
      by default, but package configuration can do it.
      This will only include non-DLL, non-extension modules, i.e. actual data
      files. After a ":" optionally a filename pattern can be given as
      well, selecting only matching files. Examples:
      "--include-package-data=package_name" (all files)
      "--include-package-data=package_name=*.txt" (only certain type)
      "--include-package-data=package_name=some_filename.dat (concrete file)
      Default empty.
  include-data-files:
    description: |
      Include data files by filenames in the distribution. There are many
      allowed forms. With '--include-data-files=/path/to/file/*.txt=folder_name/some.txt' it
      will copy a single file and complain if it's multiple. With
      '--include-data-files=/path/to/files/*.txt=folder_name/' it will put
      all matching files into that folder. For recursive copy there is a
      form with 3 values that '--include-data-files=/path/to/scan=folder_name/=**/*.txt'
      that will preserve directory structure. Default empty.
  include-data-dir:
    description: |
      Include data files from complete directory in the distribution. This is
      recursive. Check '--include-data-files' with patterns if you want non-recursive
      inclusion. An example would be '--include-data-dir=/path/some_dir=data/some_dir'
      for plain copy, of the whole directory. All non-code files are copied, if you
      want to use '--noinclude-data-files' option to remove them. Default empty.
  noinclude-data-files:
    description: |
      Do not include data files matching the filename pattern given. This is against
      the target filename, not source paths. So to ignore a file pattern from package
      data for 'package_name' should be matched as 'package_name/*.txt'. Or for the
      whole directory simply use 'package_name'. Default empty.
  include-onefile-external-data:
    description: |
      Include the specified data file patterns outside of the onefile binary,
      rather than on the inside. Makes only sense in case of '--onefile'
      compilation. First files have to be specified as included with other
      `--include-*data*` options, and then this refers to target paths
      inside the distribution. Default empty.
  include-raw-dir:
    description: |
      Include raw directories completely in the distribution. This is
      recursive. Check '--include-data-dir' to use the sane option.
      Default empty.

  ### Control the inclusion of modules and packages in result. ###
  include-package:
    description: 'Include a whole package. Give as a Python namespace, e.g. "some_package.sub_package" and Nuitka will then find it and include it and all the modules found below that disk location in the binary or extension module it creates, and make it available for import by the code. To avoid unwanted sub packages, e.g. tests you can e.g. do this "--nofollow-import-to=*.tests". Default empty.'
  include-module:
    description: 'Include a single module. Give as a Python namespace, e.g. "some_package.some_module" and Nuitka will then find it and include it in the binary or extension module it creates, and make it available for import by the code. Default empty.'
  include-plugin-directory:
    description: "Include the content of that directory, no matter if it is used by the given main program in a visible form. Overrides all other inclusion options. Can be given multiple times. Default empty."
  include-plugin-files:
    description: "Include into files matching the PATTERN. Overrides all other follow options. Can be given multiple times. Default empty."
  prefer-source-code:
    description: "For already compiled extension modules, where there is both a source file and an extension module, normally the extension module is used, but it should be better to compile the module from available source code for best performance. If not desired, there is --no- prefer-source-code to disable warnings about it. Default off."
  nofollow-import-to:
    description: "Do not follow to that module name even if used, or if a package name, to the whole package in any case, overrides all other options. Can be given multiple times. Default empty."
  user-package-configuration-file:
    description: "User provided YAML file with package configuration. You can include DLLs, remove bloat, add hidden dependencies. Check User Manual for a complete description of the format to use. Can be given multiple times. Defaults to empty."

  ### Onefile behavior details ###
  onefile-tempdir-spec:
    description: "Use this as a folder to unpack onefile. Defaults to '%TEMP%\\onefile_%PID%_%TIME%', but e.g. '%CACHE_DIR%/%COMPANY%/%PRODUCT%/%VERSION%' would be cached and good too."
  onefile-child-grace-time:
    description: "When stopping the child, e.g. due to CTRL-C or shutdown, how much time to allow before killing it the hard way. Unit is ms. Default 5000."
  onefile-no-compression:
    description: "When creating the onefile, disable compression of the payload. Default is false."

  warn-implicit-exceptions:
    description: |
      Enable warnings for implicit exceptions detected at compile time.
  warn-unusual-code:
    description: |
      Enable warnings for unusual code detected at compile time.
  assume-yes-for-downloads:
    description: |
      Allow Nuitka to download external code if necessary, e.g. dependency
      walker, ccache, and even gcc on Windows. To disable, redirect input
      from nul device, e.g. "</dev/null" or "<NUL:". Default is to prompt.
    default: true
  nowarn-mnemonic:
    description: |
      Disable warning for a given mnemonic. These are given to make sure you are aware of
      certain topics, and typically point to the Nuitka website. The mnemonic is the part
      of the URL at the end, without the HTML suffix. Can be given multiple times and
      accepts shell pattern. Default empty.

  ### Deployment modes ###
  deployment:
    description: |
      Disable code aimed at making finding compatibility issues easier. This
      will e.g. prevent execution with "-c" argument, which is often used by
      code that attempts run a module, and causes a program to start itself
      over and over potentially. Disable once you deploy to end users, for
      finding typical issues, this is very helpful during development. Default
      off.
  no-deployment-flag:
    description: |
      Keep deployment mode, but disable selectively parts of it. Errors from
      deployment mode will output these identifiers. Default empty.

  ### Output choices ##
  output-dir:
    description: "Directory for output builds"
    default: build
  output-file:
    description: "Specify how the executable should be named. For extension modules there is no choice, also not for standalone mode and using it will be an error. This may include path information that needs to exist though. Defaults to '<program_name>' on this platform. .exe)"

  ### Console handling ###
  disable-console:
    description: "Obsolete as of Nuitka 2.3: When compiling for Windows or macOS, disable the console window and create a GUI application. Defaults to false."
  enable-console:
    description: "Obsolete as of Nuitka 2.3: When compiling for Windows or macOS, enable the console window and create a GUI application. Defaults to false and tells Nuitka your choice is intentional."

  ### Version information ###
  company-name:
    description: |
      Name of the company to use in version information. Defaults to unused.
  product-name:
    description: |
      Name of the product to use in version information. Defaults to base filename of the binary.
  file-version:
    description: |
      File version to use in version information. Must be a sequence of up to 4
      numbers, e.g. 1.0 or 1.0.0.0, no more digits are allowed, no strings are
      allowed. Defaults to unused.
  product-version:
    description: |
      Product version to use in version information. Same rules as for file version.
      Defaults to unused.
  file-description:
    description: |
      Description of the file used in version information. Windows only at this time. Defaults to binary filename.
  copyright:
    description: |
      Copyright used in version information. Windows/macOS only at this time. Defaults to not present.
  trademarks:
    description: |
      Trademark used in version information. Windows/macOS only at this time. Defaults to not present.

  ### General OS controls ###
  force-stdout-spec:
    description: |
      Force standard output of the program to go to this location. Useful for programs with
      disabled console and programs using the Windows Services Plugin of Nuitka commercial.
      Defaults to not active, use e.g. '{PROGRAM_BASE}.out.txt', i.e. file near your program,
      check User Manual for full list of available values.
  force-stderr-spec:
    description: |
      Force standard error of the program to go to this location. Useful for programs with
      disabled console and programs using the Windows Services Plugin of Nuitka commercial.
      Defaults to not active, use e.g. '{PROGRAM_BASE}.err.txt', i.e. file near your program,
      check User Manual for full list of available values.

  ### Windows specific controls ###
  windows-console-mode:
    description: |
      Select console mode to use. Default mode is 'force' and creates a
      console window unless the program was started from one. With 'disable'
      it doesn't create or use a console at all. With 'attach' an existing
      console will be used for outputs. With 'hide' a newly spawned console
      will be hidden and an already existing console will behave like
      'force'. Default is 'force'.

  windows-icon-from-ico:
    description: |
      Add executable icon. Can be given multiple times for different resolutions
      or files with multiple icons inside. In the later case, you may also suffix
      with #<n> where n is an integer index starting from 1, specifying a specific
      icon to be included, and all others to be ignored.
  windows-icon-from-exe:
    description: |
      Copy executable icons from this existing executable (Windows only).
  onefile-windows-splash-screen-image:
    description: |
      When compiling for Windows and onefile, show this while loading the application. Defaults to off.
  windows-uac-admin:
    description: |
      Request Windows User Control, to grant admin rights on execution. (Windows only). Defaults to off.
  windows-uac-uiaccess:
    description: |
      Request Windows User Control, to enforce running from a few folders only, remote
      desktop access. (Windows only). Defaults to off.

  ### macOS specific controls: ###
  macos-create-app-bundle:
    description: |
      When compiling for macOS, create a bundle rather than a plain binary
      application. This is the only way to unlock the disabling of console,
      get high DPI graphics, etc. and implies standalone mode. Defaults to
      off.
  macos-target-arch:
    description: |
      What architectures is this to supposed to run on. Default and limit
      is what the running Python allows for. Default is "native" which is
      the architecture the Python is run with.
  macos-app-icon:
    description: |
      Add icon for the application bundle to use. Can be given only one time. Defaults to Python icon if available.
  macos-signed-app-name:
    description: |
      Name of the application to use for macOS signing. Follow "com.YourCompany.AppName"
      naming results for best results, as these have to be globally unique, and will
      potentially grant protected API accesses.
  macos-app-name:
    description: |
      Name of the product to use in macOS bundle information. Defaults to base
      filename of the binary.
  macos-app-mode:
    description: |
      Mode of application for the application bundle. When launching a Window, and appearing
      in Docker is desired, default value "gui" is a good fit. Without a Window ever, the
      application is a "background" application. For UI elements that get to display later,
      "ui-element" is in-between. The application will not appear in dock, but get full
      access to desktop when it does open a Window later.
  macos-sign-identity:
    description: |
      When signing on macOS, by default an ad-hoc identify will be used, but with this
      option your get to specify another identity to use. The signing of code is now
      mandatory on macOS and cannot be disabled. Use "auto" to detect your only identity
      installed. Default "ad-hoc" if not given.
  macos-sign-notarization:
    description: |
      When signing for notarization, using a proper TeamID identity from Apple, use
      the required runtime signing option, such that it can be accepted.
  macos-app-version:
    description: |
      Product version to use in macOS bundle information. Defaults to "1.0" if
      not given.
  macos-app-protected-resource:
    description: |
      Request an entitlement for access to a macOS protected resources, e.g.
      "NSMicrophoneUsageDescription:Microphone access for recording audio."
      requests access to the microphone and provides an informative text for
      the user, why that is needed. Before the colon, is an OS identifier for
      an access right, then the informative text. Legal values can be found on
      https://developer.apple.com/documentation/bundleresources/information_property_list/protected_resources and
      the option can be specified multiple times. Default empty.

  ### Linux specific controls: ###
  linux-icon:
    description: |
      Add executable icon for onefile binary to use. Can be given only one time. Defaults to Python icon if available.

  ### data file embedding (commercial only) ###
  embed-data-files-compile-time-pattern:
    description: Pattern of data files to embed for use during compile time. These should match target filenames.
  embed-data-files-run-time-pattern:
    description: Pattern of data files to embed for use during run time. These should match target filenames.
  embed-data-files-qt-resource-pattern:
    description: Pattern of data files to embed for use with Qt at run time. These should match target filenames.
  embed-debug-qt-resources:
    description: For debugging purposes, print out information for Qt resources not found.

  ### traceback encryption (commercial only) ###
  encryption-key:
    description: "The key to use."
  encrypt-stdout:
    description: "Apply encryption to standard output."
  encrypt-stderr:
    description: "Apply encryption to standard error."

  ### Backend C compiler choices. ###
  clang:
    description: |
      Enforce the use of clang. On Windows this requires a working Visual
      Studio version to piggy back on. Defaults to off.
  mingw64:
    description: |
      Enforce the use of MinGW64 on Windows. Defaults to off unless MSYS2 with MinGW Python is used.
  msvc:
    description: |
      Enforce the use of specific MSVC version on Windows. Allowed values
      are e.g. "14.3" (MSVC 2022) and other MSVC version numbers, specify
      "list" for a list of installed compilers, or use "latest".

      Defaults to latest MSVC being used if installed, otherwise MinGW64
      is used.
  jobs:
    description: |
      Specify the allowed number of parallel C compiler jobs. Negative values
      are system CPU minus the given value. Defaults to the full system CPU
      count unless low memory mode is activated, then it defaults to 1.
  lto:
    description: |
      Use link time optimizations (MSVC, gcc, clang). Allowed values are
      "yes", "no", and "auto" (when it's known to work). Defaults to
      "auto".
  static-libpython:
    description: |
      Use static link library of Python. Allowed values are "yes", "no",
      and "auto" (when it's known to work). Defaults to "auto".
  cf-protection:
    description: |
      This option is gcc specific. For the gcc compiler, select the
      "cf-protection" mode. Default "auto" is to use the gcc default
      value, but you can override it, e.g. to disable it with "none"
      value. Refer to gcc documentation for "-fcf-protection" for the
      details.

  ### Debug features ###
  debug:
    description: |
      Executing all self checks possible to find errors in Nuitka, do not use for
      production. Defaults to off.
  no-debug-immortal-assumptions:
    description: |
      Disable check normally done with "--debug". With Python3.12+ do not check known
      immortal object assumptions. Some C libraries corrupt them. Defaults to check
      being made if "--debug" is on.
  unstripped:
    description: |
      Keep debug info in the resulting object file for better debugger interaction.
      Defaults to off.
  trace-execution:
    description: |
      Traced execution output, output the line of code before executing it.
      Defaults to off.
  xml:
    description: |
      Write the internal program structure, result of optimization in XML form to given filename.
  experimental:
    description: |
      Use features declared as 'experimental'. May have no effect if no experimental
      features are present in the code. Uses secret tags (check source) per
      experimented feature.
  low-memory:
    description: |
      Attempt to use less memory, by forking less C compilation jobs and using
      options that use less memory. For use on embedded machines. Use this in
      case of out of memory problems. Defaults to off.


  ### action controls: ###
  disable-cache:
    description: "Disables caching of compiled binaries. Defaults to false."


runs:
  using: "composite"
  steps:
    - name: Setup Environment Variables
      if: ${{ !inputs.disable-cache }}
      shell: bash
      run: |
        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
    - name: Install Dependencies
      shell: bash
      run: |
        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"
    - name: Install ccache
      # TODO: Proper "in" test could make sense here.
      if: ${{ inputs.disable-cache != 'ccache' && runner.os == 'Linux' }}
      shell: bash
      run: |
        sudo apt-get install -y ccache
    - name: Cache Nuitka cache directory
      if: ${{ !inputs.disable-cache }}
      uses: actions/cache@v4
      with:
        path: ${{ env.NUITKA_CACHE_DIR }}
        key: ${{ runner.os }}-${{ runner.arch }}-python-${{ env.PYTHON_VERSION }}-nuitka-${{ github.sha }}
        restore-keys: |
          ${{ runner.os }}-${{ runner.arch }}-python-${{ env.PYTHON_VERSION }}-
          ${{ runner.os }}-${{ runner.arch }}-python-
          ${{ runner.os }}-${{ runner.arch }}-

    - name: Build with Nuitka
      env:
        NUITKA_WORKFLOW_INPUTS: ${{ toJson(inputs) }}
      shell: bash
      run: |
        set -e
        python -m nuitka --github-workflow-options
      working-directory: ${{ inputs.working-directory }}