docs: Linux platform

content/best-practices/platform-file-split-or-not.md

@@ -23,12 +23,13 @@ Using platform files:
 
 - `file.ios.ts`
 - `file.android.ts`
+- `file.linux.ts` (when targeting [Linux](/guide/linux/))
 
 The advent of tree shaking and webpack builds does away with quite a bit of worry in this area however there's a few things to consider here.
 
 ## Conditional with tree shaking
 
-When speaking of tree shaking ever since NativeScript 7, you've been able to use `__ANDROID__` or `global.isIOS` and anytime those are used as conditional splits in your code, only the applicable code for the platform that's being built would actually end up in your compiled code alleviating a lot of concern here.
+When speaking of tree shaking ever since NativeScript 7, you've been able to use `__ANDROID__`, `__LINUX__` or `global.isIOS` and anytime those are used as conditional splits in your code, only the applicable code for the platform that's being built would actually end up in your compiled code alleviating a lot of concern here.
 
 ## Future maintenance
 

content/configuration/nativescript.md

@@ -37,7 +37,7 @@ export default {
 id: string = 'com.mycompany.myapp'
 ```
 
-Controls the Application ID of your app, this setting can be overridden per platform via [ios.id](#ios-id) and [android.id](#android-id).
+Controls the Application ID of your app, this setting can be overridden per platform via [ios.id](#ios-id), [android.id](#android-id) and [linux.id](#linux-id).
 
 ### main
 
@@ -163,6 +163,14 @@ ios: Object = {}
 
 See [iOS Configuration Reference](#ios-configuration-reference)
 
+### linux
+
+```ts
+linux: Object = {}
+```
+
+See [Linux Configuration Reference](#linux-configuration-reference)
+
 ### hooks
 
 ```ts
@@ -508,6 +516,109 @@ ios: {
 }
 ```
 
+## Linux Configuration Reference
+
+::: warning Experimental
+The Linux platform is experimental. See [Developing for Linux](/guide/linux/).
+:::
+
+### <span>linux.id</span>
+
+```ts
+linux.id: string = 'org.mycompany.MyApp';
+```
+
+Controls the app id on Linux, this setting overrides the value set in [id](#id). It names the app's desktop entry (`<id>.desktop`), icon and install folder, and must be a reverse DNS name (letters, digits, `_` and `-`, separated by dots).
+
+### linux.window
+
+```ts
+linux.window: {
+  width?: number
+  height?: number
+  minWidth?: number
+  minHeight?: number
+  resizable?: boolean
+  title?: string
+} = {}
+```
+
+The initial size of the app's windows, in logical pixels, and their minimum size. Defaults to `1024` by `768`, resizable, with the app name as the title.
+
+```ts
+export default {
+  // ...
+  linux: {
+    window: {
+      width: 1280,
+      height: 800,
+      minWidth: 480,
+      minHeight: 360,
+    },
+  },
+} as NativeScriptConfig
+```
+
+### linux.appearance
+
+```ts
+linux.appearance: 'system' | 'light' | 'dark' = 'system';
+```
+
+Keeps the app's native controls light or dark, whatever the desktop uses. Defaults to `'system'`, which follows the desktop.
+
+### linux.v8Flags
+
+```ts
+linux.v8Flags: string = '--expose_gc';
+```
+
+V8 flags set before the runtime starts. During development, the `NS_V8_FLAGS` environment variable adds to them.
+
+### linux.bundle
+
+```ts
+linux.bundle: boolean = true;
+```
+
+When enabled, **release** builds pack the app's files into one read-only `app.nsbundle` next to the executable. App code reads it with the usual file APIs, and writing to app files fails. Debug builds always use a plain folder. Defaults to `true`.
+
+### linux.bundleUnpack
+
+```ts
+linux.bundleUnpack: string[] = ['fonts/**'];
+```
+
+Globs, relative to the app folder, of files that are kept as real files in `app.nsbundle.unpacked`, for code that opens them by path. Native addons (`.node` and `.so` files) are always unpacked. Defaults to `['fonts/**']`.
+
+### linux.sourceProtect
+
+```ts
+linux.sourceProtect: boolean = true;
+```
+
+When enabled, **release** builds encrypt the `app.nsbundle` with a key generated for each build and embedded in the executable, so the app's sources aren't shipped readable. Defaults to `false`.
+
+This can be overridden per build with `--source-protect` or `--no-source-protect`. The encryption key can be provided with `--source-protect-key-hex <key>` or the `NS_LINUX_BUNDLE_KEY` environment variable. If source protection is requested and can't be applied, the build fails.
+
+### linux.fuses
+
+```ts
+linux.fuses: {
+  bundleIntegrity?: boolean
+  onlyLoadAppFromBundle?: boolean
+  inspector?: boolean
+  envOverrides?: boolean
+} = {}
+```
+
+Settings written into the executable of **release** builds:
+
+- `bundleIntegrity` - refuse an `app.nsbundle` that doesn't match the build. Defaults to `true` when the app is bundled.
+- `onlyLoadAppFromBundle` - only run the app from `app.nsbundle`, never from a plain app folder. Defaults to `true` when the app is bundled.
+- `inspector` - allow attaching a debugger with `--inspect`. Defaults to `false`.
+- `envOverrides` - honor the runtime's command line flags and environment variables (such as `NS_V8_FLAGS`). Defaults to `false`.
+
 ## Hooks Configuration Reference
 
 ```ts

content/configuration/vite.md

@@ -381,7 +381,8 @@ Additional env flags that are passed by the CLI automatically
 - `--env.android` - `true` when running on Android
 - `--env.ios` - `true` when running on iOS
 - `--env.visionos` - `true` when running on visionOS
-- `--env.platform=<platform>` - for specifying the platform to use. Can be `android`, `ios`, or `visionos`.
+- `--env.linux` - `true` when running on Linux
+- `--env.platform=<platform>` - for specifying the platform to use. Can be `android`, `ios`, `visionos`, or `linux`.
 - `--env.hmr` - `true` when building with HMR enabled
 
 ## Global "magic" variables
@@ -418,6 +419,12 @@ We define a few useful globally available variables that you can use to alter lo
     // we are running on an Apple platform
   }
   ```
+- `__LINUX__`, `true` when the platform is Linux
+  ```ts
+  if (__LINUX__) {
+    // we are running on Linux
+  }
+  ```
 
 ::: details The following variables are also defined, but are primarily intended to be used by NativeScript Core internally, or plugins that wish to use these.
 

content/configuration/webpack.md

@@ -96,7 +96,8 @@ Additional env flags that are usually passed by the CLI automatically
 - `--env.nativescriptLibPath` - path to the currently running CLI's library.
 - `--env.android` - `true` when running on android
 - `--env.ios` - `true` when running on ios
-- `--env.platform=<platform>` - for specifying the platform to use. Can be `android` or `ios`, or a custom platform in the future.
+- `--env.linux` - `true` when running on Linux
+- `--env.platform=<platform>` - for specifying the platform to use. Can be `android`, `ios`, `linux`, or a custom platform.
 - `--env.hmr` - `true` when building with HMR enabled
 
 ## Global "magic" variables
@@ -121,6 +122,12 @@ We define a few useful globally available variables that you can use to alter lo
     // we are running on iOS
   }
   ```
+- `__LINUX__` (also available as `global.isLinux`) - `true` when the platform is Linux
+  ```ts
+  if (__LINUX__) {
+    // we are running on Linux
+  }
+  ```
 
 ::: details The following variables are also defined, but are primarily intended to be used by NativeScript Core internally, or plugins that wish to use these.
 

content/guide/adding-native-code.md

@@ -30,6 +30,7 @@ ns native add java com.company.OtherAwesomeClass
 1. You can also manually add native code to [App_Resources](/project-structure/app-resources):
    - [Adding Java/Kotlin code to an application](/guide/native-code/android)
    - [Adding ObjectiveC/Swift Code to an application](/guide/native-code/ios)
+   - [Adding C/C++ code to a Linux application](/guide/native-code/linux)
 2. Optionally [generate TypeScript types for the added APIs](/guide/native-code/generate-typings)
 
 Additionally, NativeScript also supports Jetpack Compose and SwiftUI through plugins.

content/guide/cli-basics.md

@@ -57,6 +57,8 @@ Example output:
 | 3 | iPhone 14 Pro  | iOS      | XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX | Emulator | Connected | Local           |
 ```
 
+On a Linux host, the local machine is also listed as a `Linux` device. `ns run linux` runs the app on it (see [Developing for Linux](/guide/linux/)).
+
 ## Setting the default package manager
 
 To set the default package manager that the CLI uses (unless overridden in [nativescript.config.ts](/project-structure/nativescript-config#cli-packagemanager)):

content/guide/debugging.md

@@ -5,7 +5,7 @@ contributors:
   - rigor789
 ---
 
-There are multiple ways to debug issues in your apps, starting with the simplest form using `console.logs`. For more complex issues, you may need to use an actual debugger, like Chrome DevTools, XCode developer tools and instruments or the Android Studio developer tools.
+There are multiple ways to debug issues in your apps, starting with the simplest form using `console.logs`. For more complex issues, you may need to use an actual debugger, like Chrome DevTools, XCode developer tools and instruments, the Android Studio developer tools or GDB on Linux.
 
 ## Console
 
@@ -41,7 +41,7 @@ console.timeEnd('myLabel')
 To start a Chrome debugging session, run your app in debug mode:
 
 ```bash
-ns debug android|ios
+ns debug android|ios|linux
 ```
 
 The `ns debug` command builds and deploys the app on a connected device or emulator, in case you have multiple devices available you will need to pick one from a list, or pass in the `--device <id>` from `ns devices`.
@@ -163,3 +163,58 @@ Since NativeScript follows a standard gradle/android application structure, you
 - [Android Studio: Layout Inspector](https://developer.android.com/studio/debug/layout-inspector)
 - [Android Studio: view Logcat logs](https://developer.android.com/studio/debug/am-logcat)
 - [Androud Studio: Debug your app](https://developer.android.com/studio/debug#startdebug)
+
+## Debugging on Linux
+
+::: warning Experimental
+The Linux platform is experimental. See [Developing for Linux](/guide/linux/).
+:::
+
+### Chrome DevTools
+
+Start a debug session on the local machine with:
+
+```bash
+ns debug linux
+```
+
+The command builds and launches the app with the V8 inspector enabled. Once the inspector is listening, a URL is printed to the console:
+
+```bash
+To start debugging, open the following URL in Chrome:
+devtools://devtools/bundled/inspector.html?ws=127.0.0.1:9229/<id>
+```
+
+Open the printed URL in Google Chrome or Chromium to attach to the debugger session. The inspector listens on port `9229`, which can be changed with the `NS_LINUX_INSPECTOR_PORT` environment variable.
+
+The app also shows up in `chrome://inspect`, and other clients that speak the Chrome DevTools Protocol, such as the VS Code JavaScript debugger, can attach to `127.0.0.1:9229`.
+
+The same options as on the other platforms are supported:
+
+- `--debug-brk` - pauses on the first line of JavaScript until the debugger connects.
+- `--start` - attaches to an app that is already running with the debugger enabled (started with `ns debug linux`), without restarting it.
+- `--timeout` - number of seconds the CLI waits for the inspector to start. Default is 90 seconds.
+
+`ns run linux` doesn't start the inspector, use `ns debug linux` instead. The debugger is only available with the default `@nativescript/linux` (V8) runtime, and it is turned off in release builds unless the [`inspector` fuse](/configuration/nativescript#linux-fuses) is enabled.
+
+The debugger, console, sources, CPU profiling and memory snapshots are provided by V8's inspector. In CPU profiles, time spent in C functions is shown under the C function's name. Network requests made with `@nativescript/core` HTTP APIs are shown in the **Network** tab.
+
+### Console output
+
+`ns run linux` and `ns debug linux` stream the app's standard output and standard error (including `console` calls and uncaught errors) to your terminal. Run the CLI with `--log trace` to also see when the app starts and exits, with its exit code or signal.
+
+An app started from the desktop's app launcher writes its output wherever the desktop session sends it, usually the systemd journal (`journalctl --user -f`).
+
+### Debugging native code with GDB
+
+To debug C code (your own [native code](/guide/native-code/linux), GTK or the runtime), attach [GDB](https://www.sourceware.org/gdb/) to the running app:
+
+```bash
+ns run linux
+# in another terminal
+gdb -p $(pgrep -n <ProjectName>)
+```
+
+Native code in debug builds is compiled with `-O0 -g`, so GDB can show its sources and variables.
+
+To debug GTK warnings and critical messages, set `G_DEBUG=fatal-criticals` in the environment before running the CLI. The app then stops at the first critical message, and GDB shows where it came from.