Skip to content

Commit

Permalink
Update README file
Browse files Browse the repository at this point in the history
  • Loading branch information
@PatTheMav
PatTheMav committed Oct 31, 2024
1 parent 959fa46 commit 7f2df24
Showing 1 changed file with 182 additions and 30 deletions.
212 changes: 182 additions & 30 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,130 @@ The plugin template is meant to be used as a starting point for OBS Studio plugi
* A CMake project file
* GitHub Actions workflows and repository actions

## Set Up
## QuickStart Guide

### Build Environment

| Platform | Tool |
|-----------|--------|
| Windows | Visal Studio 17 2022 |
| macOS | XCode 16.0 |
| Windows, macOS | CMake 3.30.5 |
| Ubuntu 24.04 | CMake 3.28.3 |
| Ubuntu 24.04 | `ninja-build` |
| Ubuntu 24.04 | `pkg-config`
| Ubuntu 24.04 | `build-essential` |

### Build Steps

* Configure `buildspec.json` to contain your plugin metadata and - if necessary - update dependency information
* **Ubuntu only**: Have build dependencies installed:
* `obs-studio`[^1]
* `libgles2-mesa-dev`
* `qt6-base-dev`, `libqt6svg6-dev`, and `qt6-base-private-dev`[^2]

* Run `cmake` to configure, build, and package the plugin (elements in square brackets are optional):
* Configure: `cmake --preset <windows-x64|macos|ubuntu-x86_64>`
* `[-DENABLE_QT=ON]`[^2]
* `[-DENABLE_FRONTEND_API=ON]`[^3]
* `[-DENABLE_CCACHE=ON]`[^4]
* Build: `cmake --build --preset <windows-x64|macos|ubuntu-x86_64>`
* `[--config <Release|RelWithDebInfo|Debug>]`[^5]
* Install: `cmake --install <build_x64|build_macos|build_ubuntu>`
* `[--config <Release|RelWithDebInfo|Debug>]`[^6]
* `[--prefix <desired installation location]`
* Package: `cmake --build --preset ubuntu-x86_64 --target package` (_Ubuntu only_)

[^1]: Requires `sudo add-apt-repository --yes ppa:obsproject/obs-studio` to be run first to ensure ppa package is installed
[^2]: Only if the plugin provides its own Qt-based widgets or dialogs
[^3]: Only if the plugin interacts with the OBS Studio frontend via its frontend API
[^4]: Can be enabled to speed up local builds if necessary, refer to Ccache documentation about possible caveats
[^5]: By default `RelWithDebInfo` is used, CI will also use `Release` to generate release builds.
[^6]: This should match the same config used to build the project in the prior step.

### Debug Steps

Debugging your plugin requires an existing build of OBS-Studio, preferably a self-compiled build using Debug config. Please follow the instructrions on the `obs-studio` repository to build your own local version of the application.

#### Windows

The build system will automatically copy the plugin as well as its resources into a configuration-specific directory called `rundir` found in the project build directory. A Debug build of the plugin can thus be found in `<Path-To-Checkout>/build_<ARCHITECTURE>/rundir/Debug`. The plugin consists of its binary file (a `.dll` library) and its resources subdirectory (which should have the same name as the `.dll`).

To debug the code via MSVC, a few setup steps are necessary:

1. Change the target used for launching the project from "ALL_BUILD" (CMake's default) to your plugin target.
2. Change the "Debugger" configuration of your plugin target:
* Change the "Command" by browsing for the OBS Studio executable `obs64.exe` (preferrably a variant compiled locally)
* Change the "Working Directory" by browsing for the directory of that same `obs64.exe` was found in
* Change the "Environment" to contain two additional variables:
* `OBS_PLUGINS_PATH`
* `OBS_PLUGINS_DATA_PATH`
* Use the rundir location for both variables `<Path-To-Checkout>/build_<ARCHITECTURE>/rundir/Debug`
3. Launch a debugging session just like with any other project

#### macOS

The build system will automatically copy the plugin bundle into a configuration-specific directory called `rundir` found in the project build directory. A Debug build of the plugin can thus be found in `<Path-To-Checkout>/build_macos/rundir/Debug`.

To debug the code via Xcode, a few setup steps are necessary:

1. Copy the plugin bundle from the rundir to the OBS Studio plugin directory found in `/Users/<Your Username>/Library/Application Support/obs-studio/plugins`
2. Click on the current scheme used by Xcode and then click "Edit Scheme"
3. Select your plugin target from the list of schemes
4. In the "Run" configuration and under "Info", change the "Executable" by browsing for your local build of `OBS.app` (debugging won't work with official releases)
5. Under "Arguments", set up two environment variables:
* `OBS_PLUGINS_PATH`
* `OBS_PLUGINS_DATA_PATH`
* Use the rundir location for both variables `<Path-To-Checkout>/build_<ARCHITECTURE>/rundir/Debug`
6. Launch a debugging session just like with any other project

#### Linux

The build system will automatically copy the plugin bundle into a directory called `rundir` found in the project build directory. If a multi-config generator was used to create the build system, a configuration specific subdirectory might be used as well.

To debug the code via a chosen debugger, a few setup steps are necessary:

1. Two environment variables need to be set up:
* `OBS_PLUGINS_PATH`
* `OBS_PLUGINS_DATA_PATH`
* Use the rundir location for both variables `<Path-To-Checkout>/build_<ARCHITECTURE>/rundir`
2. Launch the debugger and have it run a local `obs` binary
3. Debug just like with any other project

### Package Steps

#### Windows

* Generate installer executable with InnoSetup:
```PowerShell
iscc <Path-To-Checkout>/build_<ARCHITECTURE>/installer-Windows.generated.iss /O"<Path-To-Checkout>/release" /F"<Your-Plugin-Name>-Installer"
```
* Generate ZIP archive:
```PowerShell
Compress-Archive -Path <Path-To-Checkout>/release/RelWithDebInfo -CompressionLevel Optimal -DestinationPath <Path-To-Checkout>/release/<Your-Plugin-Name>.zip
```

#### macOS

* Codesign package:
```Bash
productsign --sign "<Your-Developer-ID-Installer-Cert-Name>" "<Path-To-Checkout>/release/RelWithDebInfo/<Your-Plugin-Name>.pkg"
```
* Notarize package following [Apple's instructions](https://developer.apple.com/documentation/security/customizing-the-notarization-workflow#Upload-your-app-to-the-notarization-service)
* Distribute generated package in `<Path-To-Checkout>/release/RelWithDebInfo/<Your-Plugin-Name>.pkg`

#### Ubuntu
* Generate an Ubuntu-style `deb` package:
```Bash
cmake --prefix ubuntu-x86_64 --target package
```
* Generate compressed tar archive
```Bash
cd <Path-To-Checkout>/release/RelWithDebInfo
XZ_OPT=-T0 tar -cJf <Path-To-Checkout>/release/<Your-Plugin-Name>.tar.xz lib share
```

## Detailed Setup

The plugin project is set up using the included `buildspec.json` file. The following fields should be customized for an actual plugin:

Expand All @@ -18,8 +141,6 @@ The plugin project is set up using the included `buildspec.json` file. The follo
* `website`: URL of a website associated with the plugin
* `email`: Contact email address associated with the plugin
* `uuids`
* `macosPackage`: Unique (**!**) identifier for the macOS plugin package
* `macosInstaller`: Unique (**!**) identifier for the macOS plugin installer
* `windowsApp`: Unique (**!**) identifier for the Windows plugin installer

These values are read and processed automatically by the CMake build scripts, so no further adjustments in other files are needed.
Expand All @@ -32,7 +153,7 @@ Platform-specific settings are set up in the `platformConfig` section of the bui

### Set Up Build Dependencies

Just like OBS Studio itself, plugins need to be built using dependencies available either via the `obs-deps` repository (Windows and macOS) or via a distribution's package system (Linux).
Just like OBS Studio itself, plugins need to be built using dependencies available either via the `obs-deps` repository (Windows and macOS) or via a distribution's package system (Ubuntu).

#### Choose An OBS Studio Version

Expand All @@ -42,7 +163,7 @@ By default the plugin template specifies the most current official OBS Studio ve
* Plugins targeting the _latest_ version of OBS Studio might not work in older versions because the internal data structures used by `libobs` might not be compatible
* Users are encouraged to always update to the most recent version of OBS Studio available within a reasonable time after release - plugin authors have to choose for themselves if they'd rather keep up with OBS Studio releases or stay with an older version as their baseline (which might of course preclude the plugin from using functionality introduced in a newer version)

On Linux, the version used for development might be decided by the specific version available via a distribution's package management system, so OBS Studio compatibility for plugins might be determined by those versions instead.
On Ubuntu, the version used for development might be decided by the specific version available via a distribution's package management system, so OBS Studio compatibility for plugins might be determined by those versions instead.

#### Windows and macOS

Expand All @@ -52,24 +173,24 @@ Windows and macOS dependency downloads are configured in the `buildspec.json` fi
* `obs-studio`: Version of OBS Studio to build plugin with (needed for `libobs` and `obs-frontend-api`)
* `prebuilt`: Prebuilt OBS Studio dependencies
* `qt6`: Prebuilt version of Qt6 as used by OBS Studio
* `tools`: Contains additional build tools used by CI
* `tools`: Contains additional build tools used by CI (Optional)

The values should be kept in sync with OBS Studio releases and the `buildspec.json` file in use by the main project to ensure that the plugin is developed and built in sync with its target environment.

To update a dependency, change the `version` and associated `hashes` entries to match the new version. The used hash algorithm is `sha256`.

#### Linux
#### Ubuntu

Linux dependencies need to be resolved using the package management tools appropriate for the local distribution. As an example, building on Ubuntu requires the following packages to be installed:
Ubuntu dependencies need to be resolved using the package management tools appropriate for the local distribution. As an example, building on Ubuntu requires the following packages to be installed:

* Build System Dependencies:
* `cmake`
* `ninja-build`
* `pkg-config`
* Build Dependencies:
* `build-essential`
* `libobs-dev`
* Qt6 Dependencies:
* `obs-studio` - **Important:** Needs to be installed via the `ppa` package
* Qt6 Dependencies (if custom Qt widgets or dialogs are provided by the plugin):
* `qt6-base-dev`
* `libqt6svg6-dev`
* `qt6-base-private-dev`
Expand All @@ -80,47 +201,78 @@ To create a build configuration, `cmake` needs to be installed on the system. Th

* `macos`
* Universal architecture (supports Intel-based CPUs as Apple Silicon)
* Defaults to Qt version `6`
* Defaults to macOS deployment target `11.0`
* `macos-ci`
* Inherits from `macos`
* Enables compile warnings as error
* `windows-x64`
* Windows 64-bit architecture
* Defaults to Qt version `6`
* Defaults to Visual Studio 17 2022
* Defaults to Windows SDK version `10.0.18363.657`
* Defaults to Windows SDK version `10.0.22621`
* `windows-ci-x64`
* Inherits from `windows-x64`
* Enables compile warnings as error
* `linux-x86_64`
* Linux x86_64 architecture
* Defaults to Qt version `6`
* Defaults to Ninja as build tool
* Defaults to `RelWithDebInfo` build configuration
* `linux-ci-x86_64`
* Inherits from `linux-x86_64`
* Enables compile warnings as error
* `linux-aarch64`
* Provided as an experimental preview feature
* Linux aarch64 (ARM64) architecture
* Defaults to Qt version `6`
* `ubuntu-x86_64`
* Ubuntu x86_64 architecture
* Defaults to Ninja as build tool
* Defaults to `RelWithDebInfo` build configuration
* `linux-ci-aarch64`
* Inherits from `linux-aarch64`
* `ubuntu-ci-x86_64`
* Inherits from `ubuntu-x86_64`
* Enables compile warnings as error

Presets can be either specified on the command line (`cmake --preset <PRESET>`) or via the associated select field in the CMake Windows GUI. Only presets appropriate for the current build host are available for selection.
Presets can either be specified on the command line (`cmake --preset <PRESET>`) or via the associated select field in the CMake Windows GUI. Only presets appropriate for the current build host are available for selection.

Additional build system options are available to developers:

* `ENABLE_CCACHE`: Enables support for compilation speed-ups via ccache (enabled by default on macOS and Linux)
* `ENABLE_CCACHE`: Enables support for compilation speed-ups via ccache (disabled by default on macOS and Ubuntu for local builds)
* `ENABLE_FRONTEND_API`: Adds OBS Frontend API support for interactions with OBS Studio frontend functionality (disabled by default)
* `ENABLE_QT`: Adds Qt6 support for custom user interface elements (disabled by default)
* `CODESIGN_IDENTITY`: Name of the Apple Developer certificate that should be used for code signing
* `CODESIGN_TEAM`: Apple Developer team ID that should be used for code signing

## Creating Distributable Packages

#### Windows
By default, an InnoSetup script is generated by the build system and placed in the `build-<ARCHITECTURE>` sub-directory of the project named `installer-Windows.generated.iss` (with <ARCHITECTURE> being limited to just `x64` for the time being). This script file can be use with InnoSetup's `iscc` compiler to generate an installer executable:

```PowerShell
iscc <Path-To-Checkout>/build_<ARCHITECTURE>/installer-Windows.generated.iss /O"<Path-To-Checkout>/release" /F"<Your-Plugin-Name>-Installer"
```

To create a simple archive of your plugin, simply compress the contents of the chosen configuration subdirectory (e.g. `RelWithDebInfo`) inside the checkout root's `release` subdirectory with an archiving program of your choice[^7]:

```PowerShell
Compress-Archive -Path <Path-To-Checkout>/release/RelWithDebInfo -CompressionLevel Optimal -DestinationPath <Path-To-Checkout>/release/<Your-Plugin-Name>.zip
```

[^7]: Be careful to clean up the `release` directory contents after packaging your plugin to avoid re-packaging already existing packages on consecutive runs of these commands.

#### macOS

By default, the build system will automatically create a distributable package installer named `<Your-Plugin-Name>.pkg` in a subdirectory with the name of the chosen build configuration (e.g. `RelWithDebInfo`) inside the checkout root's `release` subdirectory.

For proper distribution, this package needs to be signed with a "Developer ID Installer" certificate (see below for more detailed information about signing information):

```Bash
productsign --sign "<Your-Developer-ID-Installer-Cert-Name>" "<Path-To-Checkout>/release/RelWithDebInfo/<Your-Plugin-Name>.pkg"
```

Finally, the package should also be notarized, for which [Apple provides documentation](https://developer.apple.com/documentation/security/customizing-the-notarization-workflow#Upload-your-app-to-the-notarization-service).

#### Ubuntu

CMake can be invoked to generate Ubuntu-compatible `deb` and `ddeb` packages directly, which will be put into the checkout root's `release` subdirectory:
```Bash
cmake --prefix ubuntu-x86_64 --target package
```

Alternatively, a simple compressed tar archive can be generated by simply archiving the entire contents of a directory specific to the chosen build configuration (e.g. `RelWithDebInfo` inside that same directory:
```Bash
cd <Path-To-Checkout>/release/RelWithDebInfo
XZ_OPT=-T0 tar -cJf <Path-To-Checkout>/release/<Your-Plugin-Name>.tar.xz lib share
```

Be mindful of the install prefix used for configuring the project (on Ubuntu this should be `/usr/lib/x86_64-linux-gnu` for x86_64 builds), as this becomes the required installation directory for the plugin.

## GitHub Actions & CI

Default GitHub Actions workflows are available for the following repository actions:
Expand Down

0 comments on commit 7f2df24

Please sign in to comment.