AYON Launcher

https://github.com/ynput/ayon-launcher
Admin
AYON Launcher is a desktop application that serves as the main entry point for the AYON pipeline,...
Tokens:9,415
Snippets:85
Trust Score:9.7
License:Apache-2.0
Update:8 months ago
Show doc for...
Tokens:
Raw
### Install Build Tools on Ubuntu

Source: https://github.com/ynput/ayon-launcher/blob/develop/docs/build_guides/linux.md

Installs essential build tools like git, cmake, and curl on Ubuntu systems. It also includes commands for installing Qt5 development libraries if needed to resolve 'xcb' errors.

```shell
sudo apt install build-essential checkinstall
sudo apt install git cmake curl

# For Qt5 xcb errors:
sudo apt install qt6-default
# or for Ubuntu > 20.04:
sudo apt-get install qtbase6-dev qtchooser qt6-qmake qtbase6-dev-tools
```

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

### AYON Launcher Build and Installation - Bash/PowerShell

Source: https://context7.com/ynput/ayon-launcher/llms.txt

Provides commands for building the AYON launcher from source on different operating systems. Includes steps for creating virtual environments, installing dependencies, building executables, creating installers, and uploading to a server.

```powershell
# Windows (PowerShell)
./tools/manage.ps1 create-env                   # Create Python virtual environment
./tools/manage.ps1 install-runtime-dependencies # Install PySide6, etc.
./tools/manage.ps1 build                        # Build frozen executables
./tools/manage.ps1 make-installer               # Create installer

# Upload to server
./tools/manage.ps1 upload --server https://ayon.example.com --api-key YOUR_KEY
```

```bash
# Linux/macOS (Bash)
./tools/make.sh create-env
./tools/make.sh install-runtime-dependencies
./tools/make.sh build
./tools/make.sh make-installer
./tools/make.sh upload --server https://ayon.example.com --api-key YOUR_KEY
```

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

### Create AYON Installer (PowerShell)

Source: https://github.com/ynput/ayon-launcher/blob/develop/docs/build_guides/windows.md

Creates a distributable installer for the AYON launcher. The installer files, including an .exe and a .json metadata file, will be placed in the `./build/installer/` directory.

```powershell
./tools/manage.ps1 make-installer
```

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

### Install Build Tools on CentOS 7

Source: https://github.com/ynput/ayon-launcher/blob/develop/docs/build_guides/linux.md

Installs necessary build tools such as git, cmake, and curl on CentOS 7 systems. It also provides instructions for installing Qt5 development libraries to address potential 'xcb' errors.

```shell
sudo yum install qit cmake

# For Qt5 xcb errors:
sudo yum install qt5-qtbase-devel
```

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

### Upload Installer to Server (Windows)

Source: https://github.com/ynput/ayon-launcher/blob/develop/README.md

Command to upload the AYON launcher installer to the server using PowerShell. It supports authentication via API key or username/password.

```powershell
./tools/manage.ps1 upload --server <your server> --api-key <your api key>

# Or, using username and password:
./tools/manage.ps1 upload --server <your server> --username <your admin username> --password  <your pasword>
```

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

### Upload Installer to Server (Linux/macOS)

Source: https://github.com/ynput/ayon-launcher/blob/develop/README.md

Command to upload the AYON launcher installer to the server using shell script. It supports authentication via API key or username/password.

```bash
./tools/make.sh upload --server <your server> --api-key <your api key>

# Or, using username and password:
./tools/make.sh upload --server <your server> --username <your admin username> --password  <your pasword>
```

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

### Create AYON Installer

Source: https://github.com/ynput/ayon-launcher/blob/develop/docs/build_guides/linux.md

Generates an installer package for the AYON application, which can be distributed to servers and workstations. The installer files, including a .dmg and a metadata .json file, will be located in the './build/installer/' directory.

```shell
./tools/make.sh make-installer
```

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

### Install Homebrew on macOS

Source: https://github.com/ynput/ayon-launcher/blob/develop/docs/build_guides/macos.md

Installs Homebrew, a package manager for macOS, which is used to install other required dependencies. This command downloads and executes the official Homebrew installation script.

```shell
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

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

### Boot Function - Initialize AYON Launcher

Source: https://context7.com/ynput/ayon-launcher/llms.txt

The `boot()` function is the main entry point for the AYON Launcher. It initializes the application, establishes server connections, and manages the distribution of addons and dependencies. It sets several environment variables related to the AYON installation and server connection.

```python
# start.py - Main bootstrap entry point
from start import boot

# The boot function is called automatically when AYON launcher starts
# It performs the following sequence:
# 1. Initialize launcher executable and register shim
# 2. Setup site ID for subprocess identification
# 3. Connect to AYON server
# 4. Create global API connection
# 5. Start distribution of addons and dependencies
# 6. Fill PYTHONPATH with distributed package paths

boot()

# Environment variables set during boot:
# AYON_VERSION - "1.4.4-dev"
# AYON_BUNDLE_NAME - Name of bundle in use
# AYON_SERVER_URL - URL of connected server
# AYON_EXECUTABLE - Path to launcher executable
# AYON_ROOT - Root directory of launcher
```

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

### Prepare AYON Environment and Install Dependencies (PowerShell)

Source: https://github.com/ynput/ayon-launcher/blob/develop/docs/build_guides/windows.md

Prepares the development environment by creating a virtual environment and installing Python runtime dependencies like PySide and Pillow. This script is part of the AYON launcher's tooling.

```powershell
./tools/manage.ps1 create-env
./tools/manage.ps1 install-runtime-dependencies
```

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

### Install CMake and Create-DMG using Homebrew

Source: https://github.com/ynput/ayon-launcher/blob/develop/docs/build_guides/macos.md

Installs the CMake build system and the create-dmg utility using Homebrew. CMake is essential for building the AYON application, and create-dmg is used for packaging the macOS application into a disk image.

```shell
brew install cmake create-dmg
```

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

### Install Python Development Libraries for pyenv on Ubuntu

Source: https://github.com/ynput/ayon-launcher/blob/develop/docs/build_guides/linux.md

Installs the required libraries on Ubuntu for pyenv to successfully build Python versions. This includes development headers and common libraries needed for Python compilation.

```shell
sudo apt-get update; sudo apt-get install --no-install-recommends make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev
```

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

### Prepare AYON Environment and Install Dependencies

Source: https://github.com/ynput/ayon-launcher/blob/develop/docs/build_guides/linux.md

Creates a virtual environment named '.venv' and installs Python runtime dependencies for AYON, such as PySide and Pillow. For CentOS, it sets the QT_BINDING environment variable to 'centos7' due to PySide6 compatibility.

```shell
# For CentOS, set environment variable first:
# export QT_BINDING=centos7

./tools/make.sh create-env
./tools/make.sh install-runtime-dependencies
```

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

### Install and Configure pyenv for Python Version Management

Source: https://github.com/ynput/ayon-launcher/blob/develop/docs/build_guides/linux.md

Installs pyenv, a tool for managing multiple Python versions. It configures the shell environment to use pyenv and then installs and sets a local Python version (3.9.13) for the AYON launcher repository.

```shell
curl https://pyenv.run | bash

# Add to ~/.bashrc:
export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

# Reload shell:
exec $SHELL

# Install Python 3.9.x:
pyenv install -v 3.9.13

# Navigate to repository and set local version:
cd /path/to/ayon-launcher
pyenv local 3.9.13
```

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

### Install Python Build Dependencies and Specific Python Version

Source: https://github.com/ynput/ayon-launcher/blob/develop/docs/build_guides/macos.md

Installs necessary build dependencies for Python (openssl, readline, sqlite3, xz, zlib) using Homebrew, and then installs a specific Python 3.9.x version (e.g., 3.9.13) using pyenv. This ensures a compatible Python environment for AYON development.

```shell
# install Python build dependences
brew install openssl readline sqlite3 xz zlib

# replace with up-to-date 3.9.x version
pyenv install 3.9.13
```

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

### Install Python Development Libraries for pyenv on CentOS

Source: https://github.com/ynput/ayon-launcher/blob/develop/docs/build_guides/linux.md

Installs the necessary libraries on CentOS for pyenv to compile Python versions. This covers essential development tools and libraries required for Python's build process.

```shell
yum install gcc zlib-devel bzip2 bzip2-devel readline-devel sqlite sqlite-devel openssl-devel tk-devel libffi-devel
```

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

### Install and Configure Pyenv for Python Version Management

Source: https://github.com/ynput/ayon-launcher/blob/develop/docs/build_guides/macos.md

Installs Pyenv, a tool for managing multiple Python versions, and configures the shell to use it. This is recommended for ensuring the correct Python version (3.9.x) is used for building AYON. It involves installing Pyenv via Homebrew, updating the shell configuration, and reinitializing the shell.

```shell
brew install pyenv
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
pyenv init
exec "$SHELL"
PATH=$(pyenv root)/shims:$PATH
```

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

### Create and Install Python Runtime Dependencies

Source: https://github.com/ynput/ayon-launcher/blob/develop/docs/build_guides/macos.md

Creates a virtual environment named .venv in the project's root directory and installs runtime Python dependencies such as PySide and Pillow. This step ensures all necessary libraries are available for the AYON application.

```shell
./tools/make.sh create-env
./tools/make.sh install-runtime-dependencies
```

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

### AYON Shim Deployment and Protocol Registration - Python

Source: https://context7.com/ynput/ayon-launcher/llms.txt

Manages the deployment of AYON shim executables and the registration of the `ayon-launcher://` protocol handler. Provides functions to get shim paths, check protocol registration status, and deploy shims with optional features like desktop icons.

```python
from ayon_common.utils import (
    deploy_ayon_launcher_shims,
    get_shim_executable_path,
    is_ayon_launcher_protocol_registered,
    register_ayon_launcher_protocol,
)

# Get shim executable path (platform-specific)
shim_path = get_shim_executable_path()
# Windows: {AYON_LAUNCHER_LOCAL_DIR}/shim/ayon.exe
# Linux: {AYON_LAUNCHER_LOCAL_DIR}/shim/ayon
# macOS: /Applications/AYON.app/Contents/MacOS/ayon

# Check protocol registration
if not is_ayon_launcher_protocol_registered():
    register_ayon_launcher_protocol()

# Deploy shim executables
deploy_ayon_launcher_shims(
    ensure_protocol_is_registered=True,
    create_desktop_icons=True,  # Windows only
)
```

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

### AYONDistribution - Manage Addons and Dependencies

Source: https://context7.com/ynput/ayon-launcher/llms.txt

The `AYONDistribution` class handles the downloading and installation of addons and dependency packages based on the AYON server's bundle configuration. It allows checking distribution requirements, accessing bundle information, and inspecting the state of addon and dependency distribution items.

```python
from ayon_common.distribution import AYONDistribution, BundleNotFoundError

# Create distribution controller
distribution = AYONDistribution(
    addon_dirpath=None,           # Default: AYON_ADDONS_DIR
    dependency_dirpath=None,      # Default: AYON_DEPENDENCIES_DIR
    use_staging=False,            # Use staging bundle
    use_dev=False,                # Use dev bundle
    skip_installer_dist=False,    # Skip launcher distribution
)

# Access bundle information
studio_bundle = distribution.studio_bundle_to_use
project_bundle = distribution.project_bundle_to_use
bundle_name = distribution.project_bundle_name_to_use

# Check distribution requirements
if distribution.need_distribution:
    print("Distribution needed")

if distribution.need_installer_change:
    print(f"Launcher version change required: {distribution.expected_installer_version}")

if distribution.need_installer_distribution:
    print("Installer download required")

# Get distribution items for addons
for item in distribution.get_addon_dist_items():
    dist_item = item["dist_item"]
    addon_name = item["addon_name"]
    addon_version = item["addon_version"]
    print(f"{addon_name} v{addon_version}: {dist_item.state}")

# Get dependency package distribution item
dep_item = distribution.get_dependency_dist_item()
if dep_item:
    print(f"Dependency package state: {dep_item.state}")
```

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

### Clone AYON Launcher Repository (Shell)

Source: https://github.com/ynput/ayon-launcher/blob/develop/docs/build_guides/windows.md

Clones the AYON launcher repository including its submodules. This command requires Git to be installed and accessible in your PATH.

```shell
git clone --recurse-submodules git@github.com:ynput/ayon-launcher.git
```

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

### AYON Launcher Utility Functions - Python

Source: https://context7.com/ynput/ayon-launcher/llms.txt

Provides utility functions for managing AYON launcher directories, identifying local sites, and tracking executables. Includes functions for getting storage paths, site IDs, launch arguments, executable paths, and archive/checksum operations.

```python
from ayon_common.utils import (
    get_launcher_storage_dir,
    get_launcher_local_dir,
    get_local_site_id,
    get_ayon_launch_args,
    is_staging_enabled,
    is_dev_mode_enabled,
    store_current_executable_info,
    get_executable_paths_by_version,
    extract_archive_file,
    calculate_file_checksum,
    validate_file_checksum,
)

# Storage directories
# Shared storage (addons, dependencies, shim)
storage_dir = get_launcher_storage_dir()
addons_dir = get_launcher_storage_dir("addons", create=True)
# Returns: {AYON_LAUNCHER_STORAGE_DIR}/addons

# Local storage (machine-specific, credentials cache)
local_dir = get_launcher_local_dir()
site_id_file = get_launcher_local_dir("site_id")
# Returns: {AYON_LAUNCHER_LOCAL_DIR}/site_id

# Site identification (unique per machine)
site_id = get_local_site_id()
# Returns: "adjective-noun-noun" style ID, e.g., "brave-quick-fox"
# Creates and stores if not exists

# Check environment modes
if is_staging_enabled():
    print("Staging mode active")
if is_dev_mode_enabled():
    print("Dev mode active")

# Get launch arguments for subprocess
args = get_ayon_launch_args("--headless", "--bundle", "my_bundle")
# Returns: [sys.executable, "start.py", "--headless", "--bundle", "my_bundle"]
# Or for frozen: ["/path/to/ayon", "--headless", ...]

# Executable version management
store_current_executable_info()  # Register current launcher
executables = get_executable_paths_by_version("1.4.4")
# Returns: ["/path/to/ayon-1.4.4/ayon", ...]

# Archive extraction (supports .zip, .tar, .tar.gz, .tar.xz, .tar.bz2)
extract_archive_file("/path/to/addon.zip", "/path/to/extract/")

# Checksum validation
checksum = calculate_file_checksum("/path/to/file.zip", "sha256")
is_valid = validate_file_checksum("/path/to/file.zip", expected_checksum, "sha256")
```

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

### AYON Launcher Command Line Interface - Bash

Source: https://context7.com/ynput/ayon-launcher/llms.txt

Demonstrates various command-line arguments for controlling the AYON launcher's startup behavior. Covers basic usage, bundle selection, debugging options, login procedures, and running scripts or packages.

```bash
# Basic usage
./ayon                           # Normal startup with login UI if needed
./ayon --headless               # No UI mode for automation

# Bundle selection
./ayon --bundle my_bundle       # Use specific bundle
./ayon --use-staging            # Use staging bundle
./ayon --use-dev                # Use dev bundle

# Debugging
./ayon --debug                  # Enable debug logging (sets AYON_DEBUG=1)
./ayon --verbose DEBUG          # Set specific log level
./ayon --skip-headers           # Skip console header output

# Login and initialization
./ayon --ayon-login             # Force show login dialog
./ayon init-ayon-launcher       # Initialize and register protocol

# Running scripts
./ayon /path/to/script.py       # Run Python script with AYON environment
./ayon /path/to/package/        # Run __main__.py from package
```

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

### Run AYON Launcher from Source (Linux/macOS)

Source: https://github.com/ynput/ayon-launcher/blob/develop/README.md

Command to run the AYON launcher directly from its source code on Linux and macOS after setting up the environment and dependencies.

```bash
./tools/make.sh run
```

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

### Run AYON Launcher from Source (Windows)

Source: https://github.com/ynput/ayon-launcher/blob/develop/README.md

Command to run the AYON launcher directly from its source code on Windows after setting up the environment and dependencies.

```powershell
./tools/manage.ps1 run
```

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

### Build AYON Desktop Application

Source: https://github.com/ynput/ayon-launcher/blob/develop/docs/build_guides/linux.md

Compiles the AYON desktop application. The build output, including an AYON {version}.app file, will be placed in the './build/' directory.

```shell
./tools/make.sh build
```

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

### Build AYON Desktop Executables (PowerShell)

Source: https://github.com/ynput/ayon-launcher/blob/develop/docs/build_guides/windows.md

Builds the AYON desktop executables. The output files will be located in the `./build/output/` directory. This command relies on the environment prepared in the previous step.

```powershell
./tools/manage.ps1 build
```

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

### Server Connection and Authentication with AYON

Source: https://context7.com/ynput/ayon-launcher/llms.txt

The `credentials` module handles server authentication, token management, and user login UI. It allows loading environments, checking server/login requirements, displaying a login UI, confirming credentials, and managing tokens. It also provides functions for changing users and logging out.

```python
from ayon_common.connection.credentials import (
    load_environments,
    create_global_connection,
    need_server_or_login,
    ask_to_login_ui,
    confirm_server_login,
    load_token,
    store_token,
    change_user_ui,
    logout,
)

# Load environment variables for server connection
load_environments()

# Check if server URL or login is needed
need_server, need_login = need_server_or_login()
# Returns: (False, False) if connected
# Returns: (True, True) if server URL missing
# Returns: (False, True) if token invalid/missing

# Show login UI (subprocess-based)
url, token, username = ask_to_login_ui(
    url="https://ayon.example.com",
    always_on_top=False,
    username="artist",
    force_username=False
)
# Returns: (url, token, username) on success
# Returns: (None, None, None) on cancel

# Confirm login and store credentials
confirm_server_login(url, token, username)

# Create global connection with site ID and version
create_global_connection()

# Token management
token = load_token("https://ayon.example.com")  # From keyring
store_token("https://ayon.example.com", "api_key_here")

# Change user via UI (for changing credentials)
result = change_user_ui()
# result.logged_out - User logged out
# result.restart - Server URL changed, restart needed
# result.token_changed - New token provided

# Logout from server
logout("https://ayon.example.com", token)
```

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

### Execute and Validate Distribution

Source: https://context7.com/ynput/ayon-launcher/llms.txt

Executes the distribution process and validates its success. Catches RuntimeError if distribution fails and prints an error message. Retrieves paths for Python packages after distribution.

```python
try:
    distribution.distribute()
    distribution.validate_distribution()
except RuntimeError as e:
    print(f"Distribution failed: {e}")

# Get paths to distributed packages
python_paths = distribution.get_python_paths()  # For sys.path and PYTHONPATH
sys_paths = distribution.get_sys_paths()        # For sys.path only
```

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

### Set Local Python Version using Pyenv

Source: https://github.com/ynput/ayon-launcher/blob/develop/docs/build_guides/macos.md

Sets the local Python version to 3.9.13 for the current directory using pyenv. This command ensures that subsequent Python commands within this directory will use the specified version, which is crucial for maintaining a consistent build environment.

```shell
# switch to AYON source directory
pyenv local 3.9.13
```
Tokens:
Raw