action.yml

name: Build executables or extension modules from Python projects

# spell-checker: ignore onefile,pyside,tempdir,nofollow,noinclude,uiaccess

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

description: "Build a standalone exe from python scripts using nuitka on Mac/Linux/Windows. Even supports GUIs with Qt/Pyside6 and Tkinter"

inputs:
  working-directory:
    default: "."
    description: "Directory to run nuitka"

  nuitka-version:
    default: "main"
    description: "Version of nuitka to use"

  ### Only Required Input ###
  script-name:
    required: true
    description: "Name or path to python script that is to be built"

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

  ### Nuitka Modes ###
  module:
    type: boolean
    default: false
    description: "Create an extension module executable instead of a program. Defaults to off."
  standalone:
    type: boolean
    default: true
    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 true.'
  onefile:
    type: boolean
    default: true
    description: "On top of standalone mode, enable onefile mode. This means not a folder, but a compressed executable is created and used. Defaults to true."
  assume-yes-for-downloads:
    type: boolean
    default: true
    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.'
  show-scons:
    description: "Displays the detailed C compilation info from Scons during build process (useful for debugging purposes)"
    type: boolean
    default: true

  ### Nuitka Plugins to enable. ###
  enable-plugins:
    description: "A comma separated list of plugins, such as pyside2, pyside6, tk-inter, etc."

  ### 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."

  ### Control the inclusion of modules and packages in result. ###
  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 files are copied, if you want to exclude files you need to remove them beforehand, or use "--noinclude-data-files" option to remove them. 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-package-data:
    description: "Include package data. Detects data files of packages automatically and copies them over. Can be a list. 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."

  ### 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."
  follow-import-to:
    description: "Follow to that module if used, or if a package, to the whole package. Can be given multiple times. Default empty."
  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."
    type: boolean
    default: false

  ### Compilation modes ###
  deployment:
    description: "Disables debugging helpers, that will help with runtime issues. Only enable when you find no more issues."
    type: boolean
    default: false
  no-deployment-flag:
    description: "Partially disables debugging helpers, that will help with runtime issues."

  ### 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)"
    required: false

  ### Console handling ###
  disable-console:
    type: boolean
    default: false
    description: "When compiling for Windows or macOS, disable the console window and create a GUI application. Defaults to false."
  enable-console:
    type: boolean
    default: false
    description: "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. One of file or product version is required, when a version resource needs to be added, e.g. to specify product name, or company name.
  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.0.0, only this format is allowed. One of file or product version is required, when a version resource needs to be added, e.g. to specify product name, or company name. Defaults to unused.
  product-version:
    description: Product version to use in version information. Must be a sequence of up to 4 numbers, e.g. 1.0.0.0, only this format is allowed. One of file or product version is required, when a version resource needs to be added, e.g. to specify product name, or company name. Defaults to unused.
  file-description:
    description: Description of the file use in version information.  One of file or product version is required, when a version resource needs to be added, e.g. to specify product name, or company name. Defaults to nonsense.
  copyright:
    description: Copyright information to add to version information. Defaults to empty.
  trademarks:
    description: Trademarks information to add to version information. Defaults to empty.

  ### Windows specific controls ###
  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-uac-admin:
    description: Request Windows User Control, to grant admin rights on execution. (Windows only). Defaults to off.
    type: boolean
    default: false
  windows-uac-uiaccess:
    description: "Request Windows User Control, to enforce running from a few folders only, remote desktop access. (Windows only). Defaults to off."
    type: boolean
    default: false
  mingw64:
    description: "Allows/enforces building with MinGW64 on Windows"
    type: boolean
    default: false
    required: false

  ### macOS specific controls: ###
  macos-create-app-bundle:
    description: "When compiling for macOS, create a bundle rather than a plain binary application. Currently experimental and incomplete. Currently this is the only way to unlock disabling of console. Defaults to false."
    type: boolean
    default: false
  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-target-arch:
    description: "options ('universal, 'arm64', 'x86_64') Default and limit is what the running Python allows for. Default is 'native' which is the architecture the Python is run with."
  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-mode:
    description: "options ('gui', 'background', 'ui-element') 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. 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."

  ### 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."
    type: boolean
    default: false
  encrypt-stderr:
    description: "Apply encryption to standard error."
    type: boolean
    default: false

  ### 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@v3
      with:
        path: ${{ env.NUITKA_CACHE_DIR }}
        key: ${{ runner.os }}-python-${{ env.PYTHON_VERSION }}-nuitka-${{ github.sha }}
        restore-keys: |
          ${{ runner.os }}-python-${{ env.PYTHON_VERSION }}-
          ${{ runner.os }}-python-
          ${{ runner.os }}-

    - 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 }}