Configuration basics
The configuration file is a simple INI socket.ini file in the root of the project.
The file is read on startup and the values are used to configure the project.
Sometimes it's useful to overide the values in socket.ini or keep some of the values local (e.g. [ios] simulator_device)
or secret (e.g. [ios] codesign_identity, [ios] provisioning_profile, etc.)
This can be done by creating a file called .ssrc in the root of the project.
It is possible to override both Command Line Interface (CLI) and Configuration File (INI) options.
Example:
socket.ini:
; other settings
[build]
headless = false
; other settings
.ssrc:
[build]
platform = ios ; override the `ssc build --platform` CLI option
[settings.ios] ; override the `[ios]` section in `socket.ini`
codesign_identity = "iPhone Developer: John Doe (XXXXXXXXXX)"
distribution_method = "ad-hoc"
provisioning_profile = "johndoe.mobileprovision"
simulator_device = "iPhone 15"
build
| Key | Default Value | Description |
|---|---|---|
| copy | "src" | ssc will copy everything in this directory to the build output directory. This is useful when you want to avoid bundling or want to use tools like vite, webpack, rollup, etc. to build your project and then copy output to the Socket bundle resources directory. |
| env | An list of environment variables, separated by commas. | |
| flags | Advanced Compiler Settings (ie C++ compiler -02, -03, etc). | |
| headless | false | If true, the window will never be displayed. |
| name | The name of the program and executable to be output. Can't contain spaces or special characters. Required field. | |
| output | "build" | The binary output path. It's recommended to add this path to .gitignore. |
| script | The build script. It runs before the [build] copy phase. |
build.script
| Key | Default Value | Description |
|---|---|---|
| forward_arguments | false | If true, it will pass build arguments to the build script. WARNING: this could be deprecated in the future. |
build.watch
| Key | Default Value | Description |
|---|---|---|
| sources[] | Configure your project to watch for sources that could change when running ssc. Could be a string or an array of strings |
webview
| Key | Default Value | Description |
|---|---|---|
| root | "/" | Make root open index.html |
| default_index | "" | Set default 'index.html' path to open for implicit routes |
| watch | false | Tell the webview to watch for changes in its resources |
webview.watch
| Key | Default Value | Description |
|---|---|---|
| reload | true | Configure webview to reload when a file changes |
webview.navigator.mounts
| Key | Default Value | Description |
|---|---|---|
| $HOST_HOME/directory-in-home-folder/ | ||
| $HOST_CONTAINER/directory-app-container/ | ||
| $HOST_PROCESS_WORKING_DIRECTORY/directory-in-app-process-working-directory/ |
permissions
| Key | Default Value | Description |
|---|---|---|
| allow_fullscreen | true | Allow/Disallow fullscreen in application |
| allow_microphone | true | Allow/Disallow microphone in application |
| allow_camera | true | Allow/Disallow camera in application |
| allow_user_media | true | Allow/Disallow user media (microphone + camera) in application |
| allow_geolocation | true | Allow/Disallow geolocation in application |
| allow_notifications | true | Allow/Disallow notifications in application |
| allow_sensors | true | Allow/Disallow sensors in application |
| allow_clipboard | true | Allow/Disallow clipboard in application |
| allow_bluetooth | true | Allow/Disallow bluetooth in application |
| allow_data_access | true | Allow/Disallow data access in application |
| allow_airplay | true | Allow/Disallow AirPlay access in application (macOS/iOS) only |
debug
| Key | Default Value | Description |
|---|---|---|
| flags | Advanced Compiler Settings for debug purposes (ie C++ compiler -g, etc). |
meta
| Key | Default Value | Description |
|---|---|---|
| bundle_identifier | A unique ID that identifies the bundle (used by all app stores). It's required when [meta] type is not "extension". It should be in a reverse DNS notation https://developer.apple.com/documentation/bundleresources/information_property_list/cfbundleidentifier#discussion |
|
| copyright | A string that gets used in the about dialog and package meta info. | |
| description | A short description of the app. | |
| file_limit | Set the limit of files that can be opened by your process. | |
| lang | Localization | |
| maintainer | A String used in the about dialog and meta info. | |
| title | The title of the app used in metadata files. This is NOT a window title. Can contain spaces and special characters. Defaults to name in a [build] section. | |
| type | "" | Builds an extension when set to "extension". |
| version | A string that indicates the version of the application. It should be a semver triple like 1.2.3. Defaults to 1.0.0. |
android
| Key | Default Value | Description |
|---|---|---|
| icon | The icon to use for identifying your app on Android. | |
| aapt_no_compress | Extensions of files that will not be stored compressed in the APK. | |
| enable_standard_ndk_build | Enables gradle based ndk build rather than using external native build (standard ndk is the old slow way) | |
| main_activity | Name of the MainActivity class. Could be overwritten by custom native code. | |
| manifest_permissions | Which permissions does your application need: https://developer.android.com/guide/topics/permissions/overview | |
| native_abis | To restrict the set of ABIs that your application supports, set them here. | |
| native_cflags | Used for adding custom source files and related compiler attributes. | |
| native_sources | ||
| native_makefile | ||
| sources |
ios
| Key | Default Value | Description |
|---|---|---|
| codesign_identity | signing guide: https://sockets.sh/guides/#ios-1 | |
| distribution_method | Describes how Xcode should export the archive. Available options: app-store, package, ad-hoc, enterprise, development, and developer-id. | |
| provisioning_profile | A path to the provisioning profile used for signing iOS app. | |
| simulator_device | which device to target when building for the simulator |
linux
| Key | Default Value | Description |
|---|---|---|
| categories | Helps to make your app searchable in Linux desktop environments. | |
| cmd | The command to execute to spawn the "back-end" process. | |
| icon | The icon to use for identifying your app in Linux desktop environments. |
mac
| Key | Default Value | Description |
|---|---|---|
| category | A category in the App Store | |
| cmd | The command to execute to spawn the "back-end" process. | |
| icon | The icon to use for identifying your app on MacOS. | |
| codesign_identity | TODO Signing guide: https://socketsupply.co/guides/#code-signing-certificates | |
| codesign_paths | Additional paths to codesign |
native
| Key | Default Value | Description |
|---|---|---|
| files | Files that should be added to the compile step. | |
| headers | Extra Headers |
win
| Key | Default Value | Description |
|---|---|---|
| cmd | The command to execute to spawn the “back-end” process. | |
| icon | The icon to use for identifying your app on Windows. | |
| logo | The icon to use for identifying your app on Windows. | |
| pfx | A relative path to the pfx file used for signing. |
window
| Key | Default Value | Description |
|---|---|---|
| height | The initial height of the first window. | |
| width | The initial width of the first window. |
headless
| Key | Default Value | Description |
|---|---|---|
| runner | The headless runner command. It is used when no OS specific runner is set. | |
| runner_flags | The headless runner command flags. It is used when no OS specific runner is set. | |
| runner_android | The headless runner command for Android | |
| runner_android_flags | The headless runner command flags for Android | |
| runner_ios | The headless runner command for iOS | |
| runner_ios_flags | The headless runner command flags for iOS | |
| runner_linux | The headless runner command for Linux | |
| runner_linux_flags | The headless runner command flags for Linux | |
| runner_mac | The headless runner command for MacOS | |
| runner_mac_flags | The headless runner command flags for MacOS | |
| runner_win32 | The headless runner command for Windows | |
| runner_win32_flags | The headless runner command flags for Windows |