Skip to content

Commit 2098bb2

Browse files
MustafaJafarMustafaJafar
authored
Merge pull request #371 from ynput/update-launcher-dev-docs
Update launcher Developer docs
2 parents eb54c5e + b60a2e1 commit 2098bb2

2 files changed

Lines changed: 163 additions & 99 deletions

File tree

‎website/docs/dev_launcher.md‎

Lines changed: 160 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -1,141 +1,204 @@
11
---
22
id: dev_launcher
3-
title: AYON Launcher - Introduction
4-
sidebar_label: Introduction
3+
title: AYON Launcher
4+
sidebar_label: AYON Launcher
55
---
66

77
import Tabs from '@theme/Tabs';
88
import TabItem from '@theme/TabItem';
9+
import DocCardList from '@theme/DocCardList';
910

1011
## Introduction
11-
For most recent documentation please use readme in [AYON launcher repository](https://github.com/ynput/ayon-launcher/blob/main/README.md).
1212

13-
Desktop application launcher for AYON pipeline. You need AYON launcher to be able to interact with any of the integrated applications. It acts as the main entry point into the pipeline for all artists publishing and loading data with AYON. Even though AYON launcher is a standalone desktop application, it doesn't do anything until it's connected to an AYON server instance.
13+
AYON Launcher is a standalone desktop application designed to be the primary gateway for connecting to your AYON Server. It manages the distribution of updates *including addons, dependency packages, and different versions of the launcher itself* according to your bundle configuration. Additionally, AYON Launcher is responsible for initiating the core addon logic, enabling artists to interact with AYON Pipeline.
1414

15-
The main purpose of application is to distribute updates based on current server state and to start main logic of core addon. At this moment core addon is `openpype` (this will change in near future).
15+
To function properly, AYON Launcher requires an active connection to an AYON Server instance.
1616

17-
### Building AYON Desktop application
17+
## AYON Launcher Development
1818

19-
We aim to closely follow [**VFX Reference Platform**](https://vfxplatform.com/)
19+
### Building AYON Desktop Application
2020

21-
AYON is written in Python 3 with specific elements still running in Python2 until all DCCs are fully updated. To see the list of those, that are not quite there yet, go to [VFX Python3 tracker](https://vfxpy.com/)
21+
:::info
2222

23-
[CX_Freeze](https://cx-freeze.readthedocs.io/en/latest) is used to freeze the Python code and all of its dependencies, and [Poetry](https://python-poetry.org/) for virtual environment management.
23+
You won't need to build the launcher yourself unless you are modifying the source code.
24+
You can find all official launcher builds on[ayon-launcher/releases | Github](https://github.com/ynput/ayon-launcher/releases) ready for direct download.
25+
:::
26+
27+
We aim to closely follow the [**VFX Reference Platform**](https://vfxplatform.com/).
28+
29+
We use [CX_Freeze](https://cx-freeze.readthedocs.io/en/latest) to freeze the Python code and its dependencies, and [Poetry](https://python-poetry.org/) for virtual environment management.
2430

25-
We provide comprehensive build steps:
26-
* [Windows](dev_launcher_build_windows.md)
27-
* [macOS](dev_launcher_build_macos.md)
28-
* [Linux](dev_launcher_build_linux.md)
31+
Comprehensive build steps are provided:
2932

30-
Output of the build process is installer with metadata file that can be distributed to workstations.
33+
<DocCardList />
3134

32-
### Upload installer to server
35+
The build process outputs an installer with a metadata file that can be distributed to workstations.
3336

34-
Create installer information from json file on server and upload the installer file to be downloaded by users.
37+
### Upload Installer to Server
3538

36-
### Windows
37-
Run `./tools/manage.ps1 upload --server <your server> --api-key <your api key>`
39+
`upload` command is used to create installer information from a JSON file on the server and upload the installer file for user download.
3840

39-
### Linux & macOS
40-
Run `./tools/make.sh upload --server <your server> --api-key <your api key>`
41+
The upload command has more options; use `--help` to explore them. For example, you can use a username and password instead of an API key.
4142

42-
Upload command has more options, use `--help` to investigate them. For example, it is possible to use username & password instead of api key.
43+
- On <span style={{color:'#1c2026',backgroundColor:'#00a2ed', borderRadius: '4px', padding: '2px 4px'}}>Windows</span>
44+
```bash
45+
cd <ayon-launcher-repo-clone>
46+
./tools/manage.ps1 upload --server <your server> --api-key <your api key>
47+
```
48+
- On <span style={{color:'#1c2026',backgroundColor:'#f47421', borderRadius: '4px', padding: '2px 4px'}}>Linux</span> and <span style={{color:'#1c2026',backgroundColor:'#e9eff5', borderRadius: '4px', padding: '2px 4px'}}>MacOS</span>
49+
```bash
50+
cd <ayon-launcher-repo-clone>
51+
./tools/make.sh upload --server <your server> --api-key <your api key>
52+
```
4353

54+
### Running AYON Desktop Application
4455

45-
### Running AYON Desktop application
56+
AYON can be executed either from live sources (this repository) or from "frozen code"—executables built using the steps described above.
4657

47-
AYON can be executed either from live sources (this repository) or from
48-
*"frozen code"* - executables that can be built using steps described above.
58+
<Tabs
59+
defaultValue='source'
60+
values={[
61+
{label: 'From sources', value: 'source'},
62+
{label: 'From frozen code', value: 'frozen'},
63+
]}>
4964

50-
### From sources
51-
AYON can be run directly from sources by activating virtual environment:
65+
<TabItem value='source'>
5266

53-
```sh
67+
Run AYON directly from sources by activating the virtual environment:
68+
69+
```bash
70+
cd <ayon-launcher-repo-clone>
5471
poetry run python start.py &args
5572
```
5673

57-
### From frozen code
58-
59-
You need to build AYON first. This will produce executable - `ayon.exe` and `ayon_console.exe` on Windows, `ayon` on Linux and `AYON {version}.app` for macOS.
60-
61-
#### Windows
62-
Executable `ayon_console.exe` creates console with output - useful for debugging, `ayon.exe` does not create console, but does not have any stdout or stderr output.
63-
64-
65-
Startup
66-
-------------
67-
Once AYON launcher is installed and launched there are few ways to affect what will happen next. Default behavior will ask for login to server (if user did not log in yet), then starts the distribution of updates, and eventually the main logic.
68-
69-
Main logic is now using command line handling from `openpype` addon. If a path to a python script is passed, it will start the python script as main logic instead.
70-
71-
### Arguments
72-
There are reserved global arguments that cannot be used in any cli handling:
73-
- `--bundle <BUNDLE NAME>` - Force AYON to use specific bundle instead of the one that is set in the config file. This is useful for testing new bundles before they are released.
74-
- `--verbose <LOG LEVEL>` - Change logging level to one of the following: DEBUG, INFO, WARNING, ERROR, CRITICAL.
75-
- `--debug` - Simplified way how to change verbose to DEBUG. Also sets `AYON_DEBUG` environment variable to `1`.
76-
- `--skip-headers` - Skip headers in the console output.
77-
- `--use-dev` - Use dev bundle and settings, if bundle is not explicitly defined.
78-
- `--use-staging` - Use staging settings, and use staging bundle, if bundle is not explicitly defined. Cannot be combined with staging.
79-
- `--headless` - Tell AYON to run in headless mode. No UIs are shown during bootstrap. Affects `AYON_HEADLESS_MODE` environment variable. Custom logic must handle headless mode on its own.
80-
- `--skip-bootstrap` - Skip bootstrap process. Used for inner logic of distribution.
81-
82-
### Environment variables
83-
Environment variables that are set during startup:
84-
- **AYON_VERSION** - Version of AYON launcher.
85-
- **AYON_BUNDLE_NAME** - Name of bundle that is used.
86-
- **AYON_LOG_LEVEL** - Log level that is used.
87-
- **AYON_DEBUG** - Debug flag enabled when set to '1'.
88-
- **AYON_USE_STAGING** - Use staging settings when set to '1'.
89-
- **AYON_USE_DEV** - Use dev mode settings when set to '1'.
90-
- **AYON_HEADLESS_MODE** - Headless mode flag enabled when set to '1'.
91-
- **AYON_EXECUTABLE** - Path to executable that is used to run AYON.
92-
- **AYON_ROOT** - Root to AYON launcher content.
93-
- **AYON_LAUNCHER_STORAGE_DIR** - Directory where are stored dependency packages, addons and files related to addons.
94-
- **AYON_LAUNCHER_LOCAL_DIR** - Directory where are stored user/machine specific files. This MUST NOT be shared.
95-
- **AYON_ADDONS_DIR** - Path to AYON addons directory - still used but considered as deprecated. Please rather use `AYON_LAUNCHER_STORAGE_DIR` to change location.
96-
- **AYON_DEPENDENCIES_DIR** - Path to AYON dependencies directory - still used but considered as deprecated. Please rather use `AYON_LAUNCHER_STORAGE_DIR` to change location.
97-
98-
- **AYON_MENU_LABEL** - Label for AYON menu -> TODO move to openpype addon.
99-
- **PYBLISH_GUI** - Default pyblish UI that should be used in pyblish -> TODO move to openpype addon.
100-
- **USE_AYON_SERVER** - Flag for openpype addon.
101-
102-
- **SSL_CERT_FILE** - Use certificates from 'certifi' if 'SSL_CERT_FILE' is not set.
103-
104-
Environment variables that are set for backwards compatibility with openpype addon:
105-
- **OPENPYPE_LOG_LEVEL** - Alias to **AYON_LOG_LEVEL**.
106-
- **OPENPYPE_DEBUG** - Alias to **AYON_DEBUG**.
107-
- **OPENPYPE_USE_STAGING** - Alias to **AYON_USE_STAGING**.
108-
- **OPENPYPE_HEADLESS_MODE** - Alias to **AYON_HEADLESS_MODE**.
109-
- **OPENPYPE_EXECUTABLE** - Alias to **AYON_EXECUTABLE**.
110-
- **OPENPYPE_ROOT** - Alias to **AYON_ROOT**.
111-
- **OPENPYPE_REPOS_ROOT** - Alias to **AYON_ROOT**.
112-
- **AVALON_LABEL** - Alias to **AYON_MENU_LABEL**.
113-
114-
:::note
115-
Environment variables **AYON_LAUNCHER_STORAGE_DIR** and **AYON_LAUNCHER_LOCAL_DIR** are by default set to the same folder. Path is based on OS.
116-
- Windows: `%LOCALAPPDATA%\Ynput\AYON`
74+
</TabItem>
75+
76+
<TabItem value='frozen'>
77+
78+
When installing launcher, you'll see these executables: `ayon.exe` and `ayon_console.exe` on Windows, `ayon` on Linux, and `AYON {version}.app` for macOS.
79+
80+
- On <span style={{color:'#1c2026',backgroundColor:'#00a2ed', borderRadius: '4px', padding: '2px 4px'}}>Windows</span> : `ayon.exe` and `ayon_console.exe`
81+
```bash
82+
cd <ayon-launcher-installation-location>
83+
./ayon.exe
84+
```
85+
Or
86+
```bash
87+
cd <ayon-launcher-installation-location>
88+
./ayon_console.exe
89+
```
90+
> The executable `ayon_console.exe` creates a console with output, which is useful for debugging. `ayon.exe` does not create a console and has no `stdout` or `stderr` output.
91+
92+
- On <span style={{color:'#1c2026',backgroundColor:'#f47421', borderRadius: '4px', padding: '2px 4px'}}>Linux</span> and <span style={{color:'#1c2026',backgroundColor:'#e9eff5', borderRadius: '4px', padding: '2px 4px'}}>MacOS</span> : `ayon`
93+
```bash
94+
cd <ayon-launcher-installation-location>
95+
ayon
96+
```
97+
98+
</TabItem>
99+
</Tabs>
100+
101+
## Startup
102+
103+
Once the AYON launcher is installed and launched, there are several ways to influence what happens next. By default, it will prompt for server login (if not already logged in), then start distributing updates, and eventually initiate the main logic.
104+
105+
:::tip
106+
107+
The main logic now uses command line handling from the `core` add-on. If a path to a Python script is provided, it will execute the script as the main logic instead.
108+
109+
```bash
110+
cd <ayon-launcher-installation-location>
111+
ayon /foo/bar/baz.py arg1 arg2
112+
```
113+
:::
114+
115+
### Executable Arguments
116+
117+
:::caution
118+
119+
AYON Launcher comes with [Global Executable Arguments] (ayon_launcher_artist_advanced.md#global-executable-arguments). These cannot be used in any CLI handling. i.e. you can't reuse them when implementing a [CLI Interface](dev_addon_creation.md#cli-interface) for your addon.
120+
:::
121+
122+
### Environment Variables
123+
124+
AYON launcher provides the following environment variables for its subprocesses, useful in scripting and other applications. These variables are set during startup.
125+
126+
| Environment Variable | Description |
127+
|--|--|
128+
| **AYON_VERSION** | Current desktop application version, e.g., `1.0.0`. |
129+
| **AYON_BUNDLE_NAME** | Name of the bundle in use. |
130+
| **AYON_LOG_LEVEL** | Logging level for AYON logger. |
131+
| **AYON_DEBUG** | Debug flag enabled when set to '1'. |
132+
| **AYON_USE_STAGING** | Use staging settings when set to '1'. |
133+
| **AYON_USE_DEV** | Use dev mode settings when set to '1'. |
134+
| **AYON_HEADLESS_MODE** | Headless mode flag enabled when set to '1'. |
135+
| **AYON_EXECUTABLE** | Path to the executable used for AYON subprocesses. Points to the **python** executable in the virtual environment when run from sources. If run from frozen code, it points to either `ayon` or `ayon_console` on Windows. |
136+
| **AYON_ROOT** | Root directory for AYON launcher content. |
137+
| **AYON_LAUNCHER_STORAGE_DIR** | Directory for storing dependency packages, add-ons, and related files. |
138+
| **AYON_LAUNCHER_LOCAL_DIR** | Directory for storing user/machine-specific files. **This MUST NOT be unique for each user/machine.** |
139+
| **AYON_ADDONS_DIR** | Path to AYON add-ons directory—considered deprecated. Use `AYON_LAUNCHER_STORAGE_DIR` instead. |
140+
| **AYON_DEPENDENCIES_DIR** | Path to AYON dependencies directory—considered deprecated. Use `AYON_LAUNCHER_STORAGE_DIR` instead. |
141+
| **AYON_MENU_LABEL** | Label for AYON menu. |
142+
| **USE_AYON_SERVER** | AYON mode is enabled. A flag for the openpype add-on. |
143+
| **SSL_CERT_FILE** | Use certificates from 'certifi' if 'SSL_CERT_FILE' is not set. |
144+
| **AYON_SITE_ID** | Local site identifier. |
145+
| **AYON_SERVER_URL** | URL for the logged-in AYON Server. |
146+
| **AYON_API_KEY** | API key for the logged-in AYON Server. |
147+
| **AYON_DEFAULT_SETTINGS_VARIANT** | Variant used for settings. |
148+
149+
<!-- | **AYON_USERNAME** | Set it to override system created username. | It can be used only for service API key and is used only for farm publishing. AYON launcher does not use it in any way, and does not set it.
150+
| **AYON_TMPDIR** | Set it to override default system temp directory. It supports `root` and `project` template keys, e.g. `{root[work]}/{project[name]}/temp`. | ayon-core related, AYON launcher does not use it in any way, and does not set it. -->
151+
152+
:::info
153+
154+
Environment variables **AYON_LAUNCHER_STORAGE_DIR** and **AYON_LAUNCHER_LOCAL_DIR** are set to the same folder by default. The path is based on the OS:
155+
- Windows: `%LOCALAPPDATA%\\Ynput\\AYON`
117156
- Linux: `~/.local/share/AYON`
118157
- macOS: `~/Library/Application Support/AYON`
119158
120-
It is required to set the environment variables before AYON launcher is started as it is required for bootstrap.
159+
Ensure to set these environment variables before starting the AYON launcher when applying overrides, as they are required for bootstrap.
160+
121161
:::
122162
123-
:::tip
124-
Environment variables **AYON_ADDONS_DIR** and **AYON_DEPENDENCIES_DIR** by default are relative to **AYON_LAUNCHER_STORAGE_DIR**.
163+
:::caution Deprecated Environment Variables
164+
165+
Environment variables **AYON_ADDONS_DIR** and **AYON_DEPENDENCIES_DIR** default to being relative to **AYON_LAUNCHER_STORAGE_DIR**.
125166
126167
- **AYON_ADDONS_DIR** -> `{AYON_LAUNCHER_STORAGE_DIR}/addons`
127168
- **AYON_DEPENDENCIES_DIR** -> `{AYON_LAUNCHER_STORAGE_DIR}/dependency_packages`
128169
129-
Changing their values will change where addons and dependency packages are stored even if you change **AYON_LAUNCHER_STORAGE_DIR**!
170+
Changing their values will alter where addons and dependency packages are stored, even if you change **AYON_LAUNCHER_STORAGE_DIR**!
171+
130172
:::
131173
132-
## Developer mode
133-
[Developer mode](dev_dev_mode.md) enables to skip the standard distribution process of addons to use local sources of addon code instead. This is useful for development of addon. Developer mode must be enabled and configured on AYON server.
174+
## Developer Mode
175+
176+
[Developer mode](dev_dev_mode.md) lets you skip the standard distribution process of add-ons and use local sources of add-on code instead. This is useful for add-on development. Developer mode must be enabled and configured on the AYON server.
134177
135-
There are 2 ways to start in developer mode using command line arguments:
136-
1. Start AYON launcher with `--bundle <dev bundle name>`. Dev bundle cannot be set as production or staging.
137-
2. Using argument flag `--use-dev`. With this argument a dev bundle is found for logged user.
178+
There are two ways to start in developer mode using command line arguments:
179+
1. Start the AYON launcher in dev mode by using the `--use-dev` argument flag. It finds the dev bundle assigned to the logged-in user.
180+
2. Choose a bundle explicitly using the `--bundle` argument, e.g., `--use-dev --bundle <dev bundle name>`.
138181
139-
Both options can be defined with environment variables `AYON_BUNDLE_NAME` and `AYON_USE_DEV` (value `1` to enable).
182+
Both options can be set with the environment variables `AYON_BUNDLE_NAME` and `AYON_USE_DEV` (set to `1` to enable).
140183
141184
Developer mode automatically disregards any production or staging information.
185+
186+
:::tip
187+
188+
For a step-by-step guide, Check [Ayon Developer Mode – Guide | Ynput Forums](https://community.ynput.io/t/ayon-developer-mode-guide/993)
189+
:::
190+
191+
## Further Information
192+
193+
For additional information, please refer to the readme in the [AYON launcher repository](https://github.com/ynput/ayon-launcher/blob/main/README.md).
194+
195+
<!--
196+
Just throwing these here for future reference.
197+
198+
- <span style={{color:'#1c2026',backgroundColor:'#00a2ed', borderRadius: '4px', padding: '2px 4px'}}>Windows</span>
199+
- <span style={{color:'#1c2026',backgroundColor:'#f47421', borderRadius: '4px', padding: '2px 4px'}}>Linux</span>
200+
- <span style={{color:'#1c2026',backgroundColor:'#e9eff5', borderRadius: '4px', padding: '2px 4px'}}>Darwin</span>
201+
- <span style={{color:'#23E0A9'}}>⬤</span> <span style={{color:'#1c2026',backgroundColor:'#23E0A9', borderRadius: '4px', padding: '2px 4px'}}>Production</span>
202+
- <span style={{color:'#ff858b'}}>⬤</span> <span style={{color:'#1c2026', backgroundColor:'#ff858b', borderRadius: '4px', padding: '2px 4px'}}>Staging</span>
203+
- <span style={{color:'#c78fff'}}>⬤</span> <span style={{color:'#1c2026',backgroundColor:'#c78fff', borderRadius: '4px', padding: '2px 4px'}}>Development</span>
204+
- <span style={{color:'#e2e2e3'}}>⬤</span> <span style={{color:'#1c2026',backgroundColor:'#e2e2e3', borderRadius: '4px', padding: '2px 4px'}}>Unarchived</span> -->

‎website/sidebars.js‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,10 @@ module.exports = {
1010
"dev_requirements",
1111
{
1212
type: "category",
13-
label: "AYON launcher",
13+
collapsed: true,
14+
label: "AYON Launcher",
15+
link: { type: "doc", id: "dev_launcher"},
1416
items: [
15-
"dev_launcher",
1617
"dev_launcher_build_windows",
1718
"dev_launcher_build_macos",
1819
"dev_launcher_build_linux",

0 commit comments

Comments
 (0)