Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion buildDocs.sh
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ set -x
apt-get update
apt-get -y install git rsync python3-pip # qttools5-dev-tools qt5-default qt5-qmake
pip3 install setuptools wheel
pip3 install docutils==0.16 sphinx>=5.0.0 sphinx-autobuild sphinx_rtd_theme>=0.5.2 myst-parser # sphinxcontrib-qthelp
pip3 install Sphinx>=8.0 sphinx-rtd-theme>=1.0 myst-parser sphinxcontrib-qthelp

#####################
# DECLARE VARIABLES #
Expand Down
50 changes: 35 additions & 15 deletions developer/architecture.md
Original file line number Diff line number Diff line change
@@ -1,41 +1,61 @@
# Architecture

Gershwin is designed with simplicity in mind. Less, but better. This page describes key elements of the Gershwin desktop. To begin with, everything should be welcoming to switchers from other operating systems but ideally even easier to use.
Gershwin is designed with simplicity in mind. Less, but better. This page describes key elements of the Gershwin desktop. Everything should be welcoming to switchers from other operating systems but ideally even easier to use.

## Frameworks

GNUstep
GNUstep is the core application framework. All native Gershwin applications are written in Objective-C using GNUstep.

## Desktop components

The minimum number of components viable to produce an efficient desktop should be used. Each component should be as simple as possible, and have as few dependencies as possible (besides the ones that are central to Gershwin, such as GNUstep). Outside dependencies that are closely tied to other outside components should be avoided. XDG specifications are considered overly complex but insufficient and should be avoided, but may be acceptable as legacy technology for compatibility reasons.
The minimum number of components viable to produce an efficient desktop should be used. Each component should be as simple as possible, and have as few dependencies as possible (besides the ones that are central to Gershwin, such as GNUstep). XDG specifications are considered overly complex but insufficient and should be avoided; they may be acceptable as legacy technology for compatibility reasons.

### Workspace

File manager that can handle `.app` bundles and also provides the Desktop.
File manager that manages `.app` bundles and provides the Desktop. Contains the Dock (application launcher), desktop icons, and file browsing. Source: `gershwin-workspace/Workspace/`.

### Menu

Global menu bar that displays the Command menu for system-wide commands, and the active application's menus. It also contains a search box to search in the menus.
Global menu bar that displays system-wide commands and the active application's menus. Implements native GNUstep menu export via the Eau theme, Canonical AppMenu via D-Bus, and legacy Gtk2/3 menu support. Source: `gershwin-components/Menu/`.

### Dock
### WindowManager

A Dock that shows icons for running and pinned applications. (In the future it should become its own window, for now it is part of the Desktop window provided by Workspace.)
Native X11 window manager written for Gershwin. Handles window positioning, resizing, focus management, compositing, and window switching (Overview). Source: `gershwin-windowmanager/WindowManager/`.

### IPC mechanism for the desktop
### LoginWindow

GNUstep IPC is used, e.g., in the Eau theme for exporting the menus of GNUstep applications to Menu.app.
Graphical login screen. Source: `gershwin-components/LoginWindow/`.

### Applications
### Terminal

Terminal emulator application. Source: `gershwin-terminal/`.

### TextEdit

Text editor application. Source: `gershwin-textedit/`.

### SystemPreferences

System settings application with pluggable preference panes. Source: `gershwin-systempreferences/SystemPreferences/`.

### UIBridge

MCP server for automating and inspecting GNUstep applications at runtime. Source: `gershwin-components/UIBridge/`.

### initgfx

Automatic graphics hardware configuration. Source: `gershwin-components/initgfx/`.

## Applications

Applications must not need to be installed. Simply downloading them, attaching an external drive containing them, or connecting to a network share containing them must be sufficient. Multiple versions of the same application must be able to co-exist.

Custom-written applications should come as Application bundles whenever possible. It is acceptable for pre-existing applications to come with legacy XDG desktop files instead.
Custom-written applications should come as application bundles whenever possible. It is acceptable for pre-existing applications to come with legacy XDG desktop files instead.

### Utilities
## Utilities

Gershwin comes with some commonly used utilities, such as a Terminal application, a Process Monitor application, etc. These are just regular applications.
Gershwin comes with commonly used utilities, such as a Terminal application, a Process Monitor application, etc. These are just regular applications bundled with the system.

### Preferences
## Preferences

Gershwin comes with commonly used preference panels, such as for configuring the network, keyboard, etc.
Gershwin comes with preference panels for commonly used settings, such as for configuring the network, keyboard, display, and other system options.
32 changes: 32 additions & 0 deletions developer/boot.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# Boot Process

Gershwin boots via the underlying operating system's init system, then starts the Gershwin session.

## System preparation

`/System/Library/Scripts/SystemPrepare.sh` configures the system to boot into Gershwin Desktop. It sets up the environment, prepares display managers, and configures autologin if desired.

## Session startup

On login, the session is started via one of:

- `startx /System/Library/Scripts/Gershwin.sh` (manual X start)
- `/System/Library/Scripts/LoginWindow.sh` (launches login window, which starts X)
- On FreeBSD/GhostBSD: `service loginwindow start`

## LoginWindow

The `LoginWindow` app (`gershwin-components/LoginWindow/`) provides the graphical login screen. It handles user authentication and starts the user's Gershwin session.

## Gershwin.sh

`/System/Library/Scripts/Gershwin.sh` is the session startup script. It:
- Sources the GNUstep environment (`GNUstep.sh`)
- Starts the WindowManager
- Starts the Menu bar
- Starts Workspace
- Starts other session components

## Monkey patching

For rapid development, the live ISO boot process supports monkey patching. See `developer/monkey-patch` for details.
50 changes: 48 additions & 2 deletions developer/building.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,51 @@
# Building Gershwin

Gershwin is built using https://github.com/gershwin-desktop/gershwin-build.
Gershwin is built using [gershwin-build](https://github.com/gershwin-desktop/gershwin-build), which orchestrates building all components from source.

The various Live ISO creation scripts also run `gershwin-build` as part of their build process.
## Quick start

```console
git clone https://github.com/gershwin-desktop/gershwin-build.git
cd gershwin-build
./bootstrap.sh
./checkout.sh
make install
```

## Per-component builds

After building the core libraries once, individual components can be rebuilt independently:

```console
cd /Developer
make corelibs # GNUstep base, gui, back, libobjc2
make workspace # gershwin-workspace
make windowmanager # gershwin-windowmanager
make components # Menu, LoginWindow, etc.
make systempreferences
make terminal
make textedit
```

## Live ISOs

The various Live ISO creation scripts (FreeBSD, Debian, Arch) run `gershwin-build` as part of their build process. See `gershwin-desktop/` for the ISO definitions.

## Build targets

| Target | Description |
|---|---|
| `corelibs` | Core libraries and system infrastructure |
| `workspace` | File manager and desktop |
| `windowmanager` | Native X11 window manager |
| `components` | System components (Menu, LoginWindow, etc.) |
| `systempreferences` | System Preferences app |
| `terminal` | Terminal emulator |
| `textedit` | Text editor |

## Requirements

- Clang/LLVM toolchain
- GNUstep make (`tools-make`)
- X.org development headers
- Per-component dependencies documented in each repository
63 changes: 62 additions & 1 deletion developer/developer-tools.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,64 @@
# Developer Tools

Section to be written
## Source tree layout

The Gershwin source tree is organized under `/Developer/Library/Sources/`:

| Directory | Purpose |
|---|---|
| `gershwin-desktop/` | Live ISO build definitions |
| `gershwin-developer/` | Core development environment, bootstrapping scripts |
| `gershwin-components/` | Applications and system services (Menu, LoginWindow, etc.) |
| `gershwin-workspace/` | File manager and desktop |
| `gershwin-windowmanager/` | Native X11 window manager |
| `gershwin-systempreferences/` | System Preferences app and preference panes |
| `gershwin-terminal/` | Terminal emulator |
| `gershwin-textedit/` | Text editor |
| `gershwin-eau-theme/` | GNUstep theme with global menu integration |
| `gershwin-system/` | System-level scripts and tools |

## Build system

Gershwin uses GNUstep make (`tools-make`). Key targets in `gershwin-developer`:

| Target | Description |
|---|---|
| `make corelibs` | Build libobjc2, GNUstep base/gui/backend, and system infrastructure |
| `make workspace` | Build gershwin-workspace |
| `make windowmanager` | Build gershwin-windowmanager |
| `make components` | Build gershwin-components (Menu, LoginWindow, etc.) |
| `make systempreferences` | Build gershwin-systempreferences |
| `make terminal` | Build gershwin-terminal |
| `make textedit` | Build gershwin-textedit |

## Starting Gershwin

After installation, start Gershwin with:

```console
startx /System/Library/Scripts/Gershwin.sh
```

Or use the login window:

```console
/System/Library/Scripts/LoginWindow.sh
```

## Testing

- **Unit tests**: Run `gnustep-tests` from a component directory
- **UI testing**: Use the `driveui` tool to drive running GNUstep apps
- **UIBridge**: MCP server for programmatic UI inspection and automation (see `developer/uibridge`)

## Debugging

- **DTrace/dtruss**: Available on FreeBSD; see `developer/tracing`
- **LLDB**: Use `lldb_exec` via UIBridge for deep process inspection
- **Logs**: UIBridge writes diagnostics to `/tmp/uibridge.log`

## Resources

- [GNUstep developer documentation](http://developer.gnustep.org/)
- [Gershwin Discussions](https://github.com/orgs/gershwin-desktop/discussions)
- `#gershwin` on irc.libera.chat
2 changes: 1 addition & 1 deletion developer/distributions.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# Note to distributions

The Gershwin Desktop is under active development, and things change rapidly. Hence, it is currently not recommended yet to attempt packaging the Gershwin Desktop in a traditional way. Instead, the use of https://github.com/gershwin-desktop/gershwin-build is highly encouraged for the time being.
The Gershwin Desktop is under active development, and things change rapidly. Hence, it is currently not recommended to attempt packaging the Gershwin Desktop in a traditional way. Instead, the use of [gershwin-build](https://github.com/gershwin-desktop/gershwin-build) is highly encouraged for the time being.

Please do not hesitate to contact the team if you have questions regarding this policy.
8 changes: 2 additions & 6 deletions developer/graphics.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,6 @@
# Graphics hardware autoconfiguration

gershwin-on-ghostbsd may use `initgfx` in the future for the automatic configuration of the graphics hardware in your computer.

:::{note}
As of January 25, 2026 this is not integrated yet.
:::
Gershwin uses `initgfx` for automatic configuration of graphics hardware.

## Theory of operation

Expand Down Expand Up @@ -66,7 +62,7 @@ If applications that are using OpenGL crash on Nvidia systems, then it may be th

## Nvidia drivers

Different versions of the Nvidia drivers exist. Unfortunately the latest version does not support all the earlier GPUs, so multiple versions of the Nvidia drivers are shipped with helloSystem to cover both new and older Nvidia GPUs. `initgfx` should automatically select a version suitable for the hardware in the computer.
Different versions of the Nvidia drivers exist. Unfortunately the latest version does not support all the earlier GPUs, so multiple versions of the Nvidia drivers may be needed to cover both new and older Nvidia GPUs. `initgfx` should automatically select a version suitable for the hardware in the computer.

To check this:

Expand Down
28 changes: 28 additions & 0 deletions developer/linux.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# Linux

Gershwin can be built and run on Linux. The primary supported distributions are Debian, Devuan, Arch Linux, and Artix.

## Building

Use [gershwin-build](https://github.com/gershwin-desktop/gershwin-build) for building from source.

For manual development setup, clone `gershwin-developer` and run the bootstrap and checkout scripts:

```console
git clone https://github.com/gershwin-desktop/gershwin-developer.git /Developer
/Developer/Library/Scripts/bootstrap.sh
/Developer/Library/Scripts/checkout.sh
cd /Developer && sudo make install
```

## Requirements

- GNUstep
- X.org or XFree86
- A window manager (WindowManager for native Gershwin, or a compatible X11 WM)

## Known differences

- The `initgfx` graphics autoconfiguration script is FreeBSD-specific
- D-Bus integration may behave slightly differently than on BSD
- Some system services use systemd or OpenRC depending on the distribution
8 changes: 4 additions & 4 deletions developer/monkey-patch.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Monkey Patching (gershwin-on-ghostbsd)
# Monkey Patching Live ISOs

It is possible to [monkey patch](https://en.wikipedia.org/wiki/Monkey_patch) the running gershwin-on-ghostbsd Live ISO as early in the boot process as possible so that developers can make changes to all aspects of an existing Live ISO without having to re-create it and without having to write the ISO to a device each time a change is to be tested.
It is possible to [monkey patch](https://en.wikipedia.org/wiki/Monkey_patch) the running Gershwin Live ISO as early in the boot process as possible so that developers can make changes to all aspects of an existing Live ISO without having to re-create it and without having to write the ISO to a device each time a change is to be tested.

With that, it allows for a very rapid development-test cycle for Live ISOs.

Expand All @@ -12,7 +12,7 @@ This feature is currently under active development and its usage is still subjec

Since an ISO file is read-only by design, the monkey patch feature allows to insert code into the early boot process from another loacation, e.g., from a USB stick.

If the user tells the system to perform the monkey patching, the early boot scripts in gershwin-on-ghostbsd execute code provided by the user (outside of the ISO), then continues the normal boot process.
If the user tells the system to perform the monkey patching, the early boot scripts execute code provided by the user (outside of the ISO), then continues the normal boot process.

## Creating the monkey patch volume

Expand Down Expand Up @@ -47,7 +47,7 @@ echo "HELLO DEVELOPERS"

# Show a message to users in the boot process
# This should be done only in rare cases since it destroys
# the gershwin-on-ghostbsd zero-text boot experience
# the Gershwin zero-text boot experience
echo "HELLO MERE MORTALS" > /dev/console

# Give users a chance to see the message
Expand Down
2 changes: 1 addition & 1 deletion developer/rpi.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Official Raspberry Pi OS image. If you use the desktop version, then LoginWindow
https://arm-files.devuan.org/RaspberryPi%20Latest%20Builds/, file `rpi-5-devuan-excalibur-*-arm64-ext4-*.zip`

:::{note}
As of January 25, 2026 this in known to be broken.
As of early 2026, Devuan is known to have build issues.
:::

SSH is preconfigured and enabled on the Devuan images.
Expand Down
Loading
Loading