Skip to content

Commit 6317fad

Browse files
PatTheMavPatTheMav
committed
Update README file
1 parent 2fc09c8 commit 6317fad

File tree

1 file changed

+131
-30
lines changed

1 file changed

+131
-30
lines changed

‎README.md‎

Lines changed: 131 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,79 @@ The plugin template is meant to be used as a starting point for OBS Studio plugi
88
* A CMake project file
99
* GitHub Actions workflows and repository actions
1010

11-
## Set Up
11+
## QuickStart Guide
12+
13+
### Build Environment
14+
15+
| Platform | Tool |
16+
|-----------|--------|
17+
| Windows | Visal Studio 17 2022 |
18+
| macOS | XCode 16.0 |
19+
| Windows, macOS | CMake 3.30.5 |
20+
| Ubuntu 24.04 | CMake 3.28.3 |
21+
| Ubuntu 24.04 | `ninja-build` |
22+
| Ubuntu 24.04 | `pkg-config`
23+
| Ubuntu 24.04 | `build-essential` |
24+
25+
### Build Steps
26+
27+
* Configure `buildspec.json` to contain your plugin metadata and - if necessary - update dependency information
28+
* **Ubuntu only**: Have build dependencies installed:
29+
* `obs-studio`[^1]
30+
* `libgles2-mesa-dev`
31+
* `qt6-base-dev`, `libqt6svg6-dev`, and `qt6-base-private-dev`[^2]
32+
33+
* Run `cmake` to configure, build, and package the plugin (elements in square brackets are optional):
34+
* Configure: `cmake --preset <windows-x64|macos|ubuntu-x86_64>`
35+
* `[-DENABLE_QT=ON]`[^2]
36+
* `[-DENABLE_FRONTEND_API=ON]`[^3]
37+
* `[-DENABLE_CCACHE=ON]`[^4]
38+
* Build: `cmake --build --preset <windows-x64|macos|ubuntu-x86_64>`
39+
* `[--config <Release|RelWithDebInfo|Debug>]`[^5]
40+
* Install: `cmake --install <build_x64|build_macos|build_ubuntu>`
41+
* `[--prefix <desired installation location]`
42+
* Package: `cmake --build --preset ubuntu-x86_64 --target package` (_Ubuntu only_)
43+
44+
[^1]: Requires `sudo add-apt-repository --yes ppa:obsproject/obs-studio` to be run first to ensure ppa package is installed
45+
[^2]: Only if the plugin provides its own Qt-based widgets or dialogs
46+
[^3]: Only if the plugin interacts with the OBS Studio frontend via its frontend API
47+
[^4]: Can be enabled to speed up local builds if necessary, refer to Ccache documentation about possible caveats
48+
[^5]: By default `RelWithDebInfo` is used, CI will also use `Release` to generate release builds.
49+
50+
### Package Steps
51+
52+
#### Windows
53+
54+
* Generate installer executable with InnoSetup:
55+
```PowerShell
56+
iscc <Path-To-Checkout>/build_<ARCHITECTURE>/installer-Windows.generated.iss /O"<Path-To-Checkout>/release" /F"<Your-Plugin-Name>-Installer"
57+
```
58+
* Generate ZIP archive:
59+
```PowerShell
60+
Compress-Archive -Path <Path-To-Checkout>/release/RelWithDebInfo -CompressionLevel Optimal -DestinationPath <Path-To-Checkout>/release/<Your-Plugin-Name>.zip
61+
```
62+
63+
#### macOS
64+
65+
* Codesign package:
66+
```Bash
67+
productsign --sign "<Your-Developer-ID-Installer-Cert-Name>" "<Path-To-Checkout>/release/RelWithDebInfo/<Your-Plugin-Name>.pkg"
68+
```
69+
* Notarize package following [Apple's instructions](https://developer.apple.com/documentation/security/customizing-the-notarization-workflow#Upload-your-app-to-the-notarization-service)
70+
* Distribute generated package in `<Path-To-Checkout>/release/RelWithDebInfo/<Your-Plugin-Name>.pkg`
71+
72+
#### Ubuntu
73+
* Generate an Ubuntu-style `deb` package:
74+
```Bash
75+
cmake --prefix ubuntu-x86_64 --target package
76+
```
77+
* Generate compressed tar archive
78+
```Bash
79+
cd <Path-To-Checkout>/release/RelWithDebInfo
80+
XZ_OPT=-T0 tar -cJf <Path-To-Checkout>/release/<Your-Plugin-Name>.tar.xz lib share
81+
```
82+
83+
## Detailed Setup
1284

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

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

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

33103
### Set Up Build Dependencies
34104

35-
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).
105+
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).
36106

37107
#### Choose An OBS Studio Version
38108

@@ -42,7 +112,7 @@ By default the plugin template specifies the most current official OBS Studio ve
42112
* 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
43113
* 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)
44114

45-
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.
115+
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.
46116

47117
#### Windows and macOS
48118

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

57127
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.
58128

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

61-
#### Linux
131+
#### Ubuntu
62132

63-
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:
133+
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:
64134

65135
* Build System Dependencies:
66136
* `cmake`
67137
* `ninja-build`
68138
* `pkg-config`
69139
* Build Dependencies:
70140
* `build-essential`
71-
* `libobs-dev`
72-
* Qt6 Dependencies:
141+
* `obs-studio` - **Important:** Needs to be installed via the `ppa` package
142+
* Qt6 Dependencies (if custom Qt widgets or dialogs are provided by the plugin):
73143
* `qt6-base-dev`
74144
* `libqt6svg6-dev`
75145
* `qt6-base-private-dev`
@@ -80,47 +150,78 @@ To create a build configuration, `cmake` needs to be installed on the system. Th
80150

81151
* `macos`
82152
* Universal architecture (supports Intel-based CPUs as Apple Silicon)
83-
* Defaults to Qt version `6`
84153
* Defaults to macOS deployment target `11.0`
85154
* `macos-ci`
86155
* Inherits from `macos`
87156
* Enables compile warnings as error
88157
* `windows-x64`
89158
* Windows 64-bit architecture
90-
* Defaults to Qt version `6`
91159
* Defaults to Visual Studio 17 2022
92-
* Defaults to Windows SDK version `10.0.18363.657`
160+
* Defaults to Windows SDK version `10.0.22621`
93161
* `windows-ci-x64`
94162
* Inherits from `windows-x64`
95163
* Enables compile warnings as error
96-
* `linux-x86_64`
97-
* Linux x86_64 architecture
98-
* Defaults to Qt version `6`
164+
* `ubuntu-x86_64`
165+
* Ubuntu x86_64 architecture
99166
* Defaults to Ninja as build tool
100-
* Defaults to `RelWithDebInfo` build configuration
101-
* `linux-ci-x86_64`
102-
* Inherits from `linux-x86_64`
103-
* Enables compile warnings as error
104-
* `linux-aarch64`
105-
* Provided as an experimental preview feature
106-
* Linux aarch64 (ARM64) architecture
107-
* Defaults to Qt version `6`
108-
* Defaults to Ninja as build tool
109-
* Defaults to `RelWithDebInfo` build configuration
110-
* `linux-ci-aarch64`
111-
* Inherits from `linux-aarch64`
167+
* `ubuntu-ci-x86_64`
168+
* Inherits from `ubuntu-x86_64`
112169
* Enables compile warnings as error
113170

114-
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.
171+
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.
115172

116173
Additional build system options are available to developers:
117174

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

181+
## Creating Distributable Packages
182+
183+
#### Windows
184+
By default an InnoSetup script is generated by the build system und 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:
185+
186+
```PowerShell
187+
iscc <Path-To-Checkout>/build_<ARCHITECTURE>/installer-Windows.generated.iss /O"<Path-To-Checkout>/release" /F"<Your-Plugin-Name>-Installer"
188+
```
189+
190+
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[^6]:
191+
192+
```PowerShell
193+
Compress-Archive -Path <Path-To-Checkout>/release/RelWithDebInfo -CompressionLevel Optimal -DestinationPath <Path-To-Checkout>/release/<Your-Plugin-Name>.zip
194+
```
195+
196+
[^6]: 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.
197+
198+
#### macOS
199+
200+
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.
201+
202+
For proper distribution this package needs to be signed with a "Developer ID Installer" certificate (see below for more detailed information about signing information):
203+
204+
```Bash
205+
productsign --sign "<Your-Developer-ID-Installer-Cert-Name>" "<Path-To-Checkout>/release/RelWithDebInfo/<Your-Plugin-Name>.pkg"
206+
```
207+
208+
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).
209+
210+
#### Ubuntu
211+
212+
CMake can be invoked to generate Ubuntu-compatible `deb` and `ddeb` packages directly, which will be put into the checkout root's `release` subdirectory:
213+
```Bash
214+
cmake --prefix ubuntu-x86_64 --target package
215+
```
216+
217+
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:
218+
```Bash
219+
cd <Path-To-Checkout>/release/RelWithDebInfo
220+
XZ_OPT=-T0 tar -cJf <Path-To-Checkout>/release/<Your-Plugin-Name>.tar.xz lib share
221+
```
222+
223+
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.
224+
124225
## GitHub Actions & CI
125226

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

0 commit comments

Comments
 (0)