diff --git a/buildDocs.sh b/buildDocs.sh index b5523f8..b91dd55 100644 --- a/buildDocs.sh +++ b/buildDocs.sh @@ -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 # diff --git a/developer/architecture.md b/developer/architecture.md index ba459c1..75426d0 100644 --- a/developer/architecture.md +++ b/developer/architecture.md @@ -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. diff --git a/developer/boot.md b/developer/boot.md new file mode 100644 index 0000000..dd7fb59 --- /dev/null +++ b/developer/boot.md @@ -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. diff --git a/developer/building.md b/developer/building.md index 33358dc..cb5d590 100644 --- a/developer/building.md +++ b/developer/building.md @@ -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 diff --git a/developer/developer-tools.md b/developer/developer-tools.md index a6a76cb..c9f69ce 100644 --- a/developer/developer-tools.md +++ b/developer/developer-tools.md @@ -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 diff --git a/developer/distributions.md b/developer/distributions.md index 17781a8..7113663 100644 --- a/developer/distributions.md +++ b/developer/distributions.md @@ -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. diff --git a/developer/graphics.md b/developer/graphics.md index 388f685..c1fa5d3 100644 --- a/developer/graphics.md +++ b/developer/graphics.md @@ -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 @@ -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: diff --git a/developer/linux.md b/developer/linux.md new file mode 100644 index 0000000..48f8362 --- /dev/null +++ b/developer/linux.md @@ -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 diff --git a/developer/monkey-patch.md b/developer/monkey-patch.md index 843bcc5..fd543c2 100644 --- a/developer/monkey-patch.md +++ b/developer/monkey-patch.md @@ -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. @@ -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 @@ -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 diff --git a/developer/rpi.md b/developer/rpi.md index 45a07c8..d053b9a 100644 --- a/developer/rpi.md +++ b/developer/rpi.md @@ -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. diff --git a/developer/uibridge.md b/developer/uibridge.md index 8d0772e..2abdbf7 100644 --- a/developer/uibridge.md +++ b/developer/uibridge.md @@ -3,67 +3,80 @@ UIBridge is a [Model Context Protocol (MCP)](https://en.wikipedia.org/wiki/Model_Context_Protocol) server for automating and inspecting GNUstep applications. You (or your AI agents) can use it to programmatically explore, control, and test real UI state and user-flows. -Typical workflow: Discover running apps → attach_app → get_full_tree / find_widgets → invoke_selector or simulate X11 input → watch_app to monitor changes. - -## UIBridge for AI agents - -What agents can do -- **Discover and attach to running apps** (list_running_apps → attach_app). -- **Inspect UI state** (get_root, get_full_tree, get_object_details) and map UI widgets to absolute screen coordinates. -- **Find and wait for widgets or text** (find_widgets, wait_for_object, wait_for_text) even when modal dialogs are present. -- **Drive apps** at multiple layers: invoke_selector / invoke_menu_item (high level), and x11_mouse_move / x11_click / x11_type (low level). -- **Monitor live changes** with notifications/ui_event (watch_app) to let agents react to UI events and adjust plans. -- **Run diagnostics** and **deep-debugging** (list_files, read_file_content, lldb_exec). - -How this integrates with VS Code and agents -- VSCode extensions call the server via MCP (tools/call) so an agent can query tools, call them, and consume JSON responses. -- Agents use the server as a grounding layer: plan (LLM) → probe UI (UIBridge) → choose action → execute → observe results → iterate. -- Prompts and prebuilt “assistant” prompts (prompts/list, prompts/get) provide structured guidance for common tasks (inspect_ui, automate_task, debug_ui_flow). - -Typical agent workflow -1. tools/call list_running_apps → pick target PID or service name. -2. tools/call attach_app → set server currentPID. -3. tools/call get_full_tree → analyze UI structure and find targets (find_widgets). -4. Execute action (invoke_selector or x11_click / invoke_menu_item). -5. tools/call watch_app (enabled) → receive notifications/ui_event and confirm outcome. -6. If needed, run lldb_exec for deep debugging or read_file_content for config/log checks. - -:::{note} -`UIBridgeServer` and target application must run under compatible user privileges (root vs user affects attachability). -::: - -Use cases -- End‑to‑end UI testing and regression checks driven by agents. -- Autonomous task execution (e.g., “Open X, perform Y, verify Z”). -- Accessibility and layout audits using absolute coordinates and full tree inspection. -- Assisted debugging workflows inside VS Code with an LLM orchestrator. - -## Installation in VSCode +Typical workflow: Launch app -> list apps -> inspect UI tree -> drive app via selectors or X11 input. + +## How it works + +UIBridge consists of three parts: + +- **Eau Theme UIBridge Service**: A component within the Eau theme that runs inside each target application's memory space, providing access to the Objective-C runtime via Distributed Objects. +- **UIBridge Server**: An MCP-compliant coordinator (`UIBridgeServer`) that manages the lifecycle of target applications and proxies requests between MCP clients and applications. +- **Common Interface**: A shared protocol definition that ensures type-safe communication and consistent serialization of Objective-C objects. + +## Installation in VSCode * Click on the "tools" icon in the text box that says "Describe what to build next" (where you enter text prompts) -* Click on the MCP icon in the "Condfigure Tools" popover (the leftmost of the three icons in the upper right hand corner of the popover) +* Click on the MCP icon in the "Configure Tools" popover (the leftmost of the three icons in the upper right corner of the popover) * Select "Command (stdio)" * Enter `/System/Library/Tools/UIBridgeServer` * Enter a name, e.g., `uibridge` -* On he left-hand side of VSCode, in the Extensions tab, you should now see the `uibridge` as an installed MCP server +* On the left-hand side of VSCode, in the Extensions tab, you should now see the `uibridge` as an installed MCP server * You can start, restart, view logs from there using the cog icon Alternatively, you can add `~/.config/Code/User/mcp.json`: -``` +```json { - "servers": { - "uibridge": { - "type": "stdio", - "command": "/System/Library/Tools/UIBridgeServer", - "args": [] - } - }, - "inputs": [] + "servers": { + "uibridge": { + "type": "stdio", + "command": "/System/Library/Tools/UIBridgeServer", + "args": [] + } + }, + "inputs": [] } ``` -Now you can use instructions like -> Start MyApplication, click on "Continue", make sure the text "Done" appears. Keep fixing the code and iterating until it works +## Core tools + +### Application lifecycle + +- **launch_app**: Launch a GNUstep application. The application will automatically register its UIBridge service via Distributed Objects if it uses the Eau theme. +- **list_apps**: List all available GNUstep applications found in standard system directories. + +### UI introspection + +- **get_root**: Retrieve the root objects of the target application (NSApp and open windows). +- **get_object_details**: Fetch detailed state for a specific object (class name, frame, titles, children). +- **list_menus**: Retrieve the entire menu hierarchy of the application. + +### Interaction and control + +- **invoke_selector**: Invoke an Objective-C selector on a remote object (`object_id`, `selector`, optional `args`). +- **invoke_menu_item**: Trigger the action associated with an `NSMenuItem`. +- **x11_mouse_move**, **x11_click**, **x11_type**: Simulate hardware input events directly via the X server. +- **lldb_exec**: Execute an arbitrary command via LLDB attached to the target process. Use for deep state analysis or memory inspection. + +### X11 window queries + +- **x11_list_windows**: Query the X11 window tree. +- **x11_window_info**: Query geometry and properties of a specific X11 window. + +## Logging + +All internal diagnostic logs are written to `/tmp/uibridge.log`. You can monitor them with: + +```console +$ tail -f /tmp/uibridge.log +``` + +## Building from source + +```console +$ cd Server +$ make +$ sudo make install +``` -in Copilot. +The server installs to `GNUSTEP_SYSTEM_TOOLS` (default: `/System/Library/Tools`). diff --git a/index.md b/index.md index 318c107..4c17656 100644 --- a/index.md +++ b/index.md @@ -41,7 +41,6 @@ glob: true developer/ux-guidelines developer/architecture -developer/boot developer/graphics developer/binary-compatibility developer/applications @@ -53,11 +52,9 @@ developer/building developer/monkey-patch developer/tracing developer/localization -developer/base developer/man developer/uibridge developer/rpi -developer/linux developer/distributions developer/contributing developer/acknowledgements diff --git a/requirements.txt b/requirements.txt index 2741eaf..7ebe918 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,10 +1,7 @@ wheel -sphinx>=5.0.0 -sphinx_rtd_theme>=0.5.2 +Sphinx>=8.0 +sphinx-rtd-theme>=1.0 sphinx-autobuild sphinx-last-updated-by-git myst-parser sphinxcontrib-qthelp -# docutils needs to be pinned for now so that lists work -# See https://github.com/readthedocs/sphinx_rtd_theme/issues/1115 for more information -docutils==0.16 diff --git a/user/components/applications.md b/user/components/applications.md index 1b50400..289dc64 100644 --- a/user/components/applications.md +++ b/user/components/applications.md @@ -1,12 +1,12 @@ # Applications -Most applications in Gershwin come in the form of __application bundles__. An application bundle is an application that looks and behaves like a file but is actually a directory, containing not only the application but also auxiliary files such as icons and other resources. To view the contents of an application bundle, right-click on it and select "Show Contents". This is useful especially for open source applications written in Objective-C, because you can interactively edit the source code and test your changes. +Most applications in Gershwin come in the form of __application bundles__. An application bundle is a directory that looks like a single file but contains the application executable and its resources. To view the contents of an application bundle, right-click on it and select "Show Contents". ![Viewing the contents of an application bundle](https://pbs.twimg.com/media/EoK9u7vXUAAJFPn?format=png) -Gershwin comes with some applications out of the box, and some applications need to be downloaded before they can be used. +Applications can be found in the menu under "System -> Applications" and in the `/Applications` folder. They can be placed anywhere on the filesystem. -You find the applications in the menu under "System -> Applications", and in the `/Applications` folder on your hard disk, although they can also be placed in other locations if you so desire. +Applications that ship with Gershwin: ```{toctree} --- @@ -15,4 +15,4 @@ glob: true --- applications/* -``` +``` diff --git a/user/components/applications/processes.md b/user/components/applications/processes.md new file mode 100644 index 0000000..6be8402 --- /dev/null +++ b/user/components/applications/processes.md @@ -0,0 +1,13 @@ +# Processes + +The Processes utility shows running applications and system processes, similar to a task manager. + +## Features + +- View all running applications +- Monitor system process activity +- End unresponsive applications + +## Location + +`/Applications/Processes/Processes.app` diff --git a/user/components/applications/system-profiler.md b/user/components/applications/system-profiler.md new file mode 100644 index 0000000..425d8de --- /dev/null +++ b/user/components/applications/system-profiler.md @@ -0,0 +1,14 @@ +# System Profiler + +System Profiler displays detailed information about the hardware and software configuration of the system. + +## Features + +- Hardware overview (CPU, memory, storage) +- Network configuration +- Graphics information +- Connected devices + +## Location + +`/Applications/SystemProfiler/SystemProfiler.app` diff --git a/user/components/preferences.md b/user/components/preferences.md index 4e230cf..f9cb37c 100644 --- a/user/components/preferences.md +++ b/user/components/preferences.md @@ -1,6 +1,6 @@ # Preferences -Gershwin comes with the following preferences applications, each of which are described in this section: +Gershwin comes with the following preferences applications: ```{toctree} --- diff --git a/user/components/preferences/systempreferences.md b/user/components/preferences/systempreferences.md new file mode 100644 index 0000000..dfb62aa --- /dev/null +++ b/user/components/preferences/systempreferences.md @@ -0,0 +1,24 @@ +# System Preferences + +System Preferences provides a centralized location for configuring Gershwin and the underlying system. It uses a pluggable preference pane architecture. + +## Preference panes + +- **Appearance**: Color schemes and themes +- **Defaults**: System-wide application defaults +- **Displays**: Display configuration +- **Energy**: Power management +- **FileSystem**: Mounted volumes and filesystem settings +- **Fonts**: Font management +- **Internet**: Network and internet settings +- **Keyboard**: Keyboard layout and shortcuts +- **ModifierKeys**: Remap modifier keys +- **Mouse**: Mouse and trackpad settings +- **Sound**: Audio input and output +- **Themes**: Desktop theme configuration +- **TimeZone**: Date and time settings +- **Volumes**: Disk and storage management + +## Location + +`/Applications/SystemPreferences/SystemPreferences.app` diff --git a/user/components/system.md b/user/components/system.md index 75dcbf4..20e73cb 100644 --- a/user/components/system.md +++ b/user/components/system.md @@ -1,6 +1,6 @@ # System components -Gershwin comes with the following system components, each of which are described in this section: +Gershwin comes with the following system components: ```{toctree} --- @@ -9,4 +9,4 @@ glob: true --- system/* -``` +``` diff --git a/user/components/system/loginwindow.md b/user/components/system/loginwindow.md index 971e9e2..ae2b9ed 100644 --- a/user/components/system/loginwindow.md +++ b/user/components/system/loginwindow.md @@ -1,10 +1,14 @@ -# LoginWindow +# Login Window -**LoginWindow** is Gershwin's session manager and login manager. It provides the initial authentication interface when starting a Gershwin session. +LoginWindow is the graphical login screen for Gershwin. It handles user authentication and session startup. ## Features -* **Authentication**: Provides a secure login interface using PAM (Pluggable Authentication Modules). -* **Session Management**: Manages the lifecycle of the Gershwin desktop session. -* **Graphical Interface**: A clean, GNUstep-based interface that matches the overall look and feel of the system. -LoginWindow ensures that only authorized users can access the system and that the environment is correctly initialized upon login. +- User selection and authentication +- Session type selection (if multiple are available) +- Password entry with secure input +- Automatic login support + +## Location + +Part of the Gershwin system; not an application the user launches directly. diff --git a/user/components/system/menu.md b/user/components/system/menu.md index d3699a7..a4e7853 100644 --- a/user/components/system/menu.md +++ b/user/components/system/menu.md @@ -1,16 +1,18 @@ # Menu -The **Gershwin Menu bar** provides a global menu at the top of the screen, similar to classical desktop environments. +The Menu application provides the global menu bar in Gershwin. It displays system-wide commands and the active application's menus in a unified menu bar at the top of the screen. ## Features -* **Global Application Menu**: Displays the menu of the currently focused application. -* **Multi-Toolkit Support**: Integrates with GNUstep, GTK, and other applications via standard DBus protocols. -* **Status Items**: Displays system status icons and notifications on the right side of the menu bar. -* **Seamless Transitions**: Uses advanced anti-flicker mechanisms for smooth menu updates when switching applications. -The Menu bar ensures a consistent interface across different types of applications, providing a unified look and feel for the Gershwin desktop. +- **Global menu bar**: Shows menus for the frontmost application +- **Action search**: Search box to quickly find menu commands +- **Multiple toolkit support**: Works with GNUstep apps, GTK apps, and Qt apps +- **D-Bus integration**: Uses the Canonical AppMenu protocol for non-native applications -## Components -* **AppMenuWidget**: Responsible for displaying and interacting with the application menus. -* **StatusItemManager**: Manages system status items and notifications. -* **ActionSearch**: Provides functionality for searching through application menus and system actions. +## Backends + +- **GNUstep native**: Uses the Eau theme's Distributed Objects IPC +- **D-Bus AppMenu**: For Qt and other D-Bus aware applications +- **GTK**: Legacy support for Gtk2/3 applications via D-Bus + +The Menu bar appears at the top of the screen and updates automatically when you switch applications. diff --git a/user/components/system/terminal.md b/user/components/system/terminal.md new file mode 100644 index 0000000..8311834 --- /dev/null +++ b/user/components/system/terminal.md @@ -0,0 +1,15 @@ +# Terminal + +Terminal is the default terminal emulator in Gershwin. It provides a command-line interface with a familiar Mac-like appearance. + +## Features + +- Multiple terminal tabs +- Configurable color schemes and fonts +- Serial terminal support +- Terminal services integration +- ANSI/VT100 escape code support + +## Location + +`/Applications/Terminal/Terminal.app` diff --git a/user/components/system/textedit.md b/user/components/system/textedit.md new file mode 100644 index 0000000..1fb6d09 --- /dev/null +++ b/user/components/system/textedit.md @@ -0,0 +1,15 @@ +# TextEdit + +TextEdit is a simple text editor for Gershwin. It supports plain text and rich text (RTF) documents. + +## Features + +- Plain text and RTF editing +- Multiple document support +- Find and replace +- Font and color styling (RTF mode) +- Recent documents + +## Location + +`/Applications/TextEdit/TextEdit.app` diff --git a/user/components/system/window-manager.md b/user/components/system/window-manager.md new file mode 100644 index 0000000..e5c17df --- /dev/null +++ b/user/components/system/window-manager.md @@ -0,0 +1,25 @@ +# Window Manager + +The Window Manager is the native X11 window manager for Gershwin. It manages window positioning, resizing, focus, compositing, and provides window switching. + +## Features + +- **Window Overview**: Bird's-eye view of all open windows (`Super+W`) +- **Snapping**: Snap windows to screen edges +- **Compositing**: Hardware-accelerated compositing +- **EWMH compliance**: Works with standard X11 window management protocols +- **Theming**: Integrates with the GNUstep theme system + +## Keyboard shortcuts + +| Shortcut | Action | +|---|---| +| `Super+W` | Toggle window overview | +| `Super+Left/Right` | Snap window to left/right half | +| `Super+Up` | Maximize window | +| `Alt+Tab` | Cycle windows | +| `Alt+~` | Cycle windows of current app | + +## Location + +`/Applications/WindowManager/WindowManager.app` diff --git a/user/components/system/workspace.md b/user/components/system/workspace.md index 6fc59b5..59ccb26 100644 --- a/user/components/system/workspace.md +++ b/user/components/system/workspace.md @@ -1,38 +1,15 @@ # Workspace -__Workspace__ is Gershwin's application for managing files, folders, and applications. It is the core of the Gershwin desktop experience. +Workspace is the file manager and desktop environment for Gershwin. It provides the desktop background, Dock, file browsing, and integration with application bundles. -Workspace offers several viewing modes: -* **Column view**: A classical multi-column browser view. -* **List view**: A detailed list of files and their properties. -* **Icon view**: Files shown as icons, with support for thumbnails. +## Features -## Core Features -* **Desktop and Dock**: Workspace provides an optional desktop with a dock for keeping track of favorites and running applications. -* **Inspector**: A powerful contents inspector with image previews, extensible through plug-ins. -* **Volume Management**: Easily check and unmount volumes. -* **Advanced Search**: Optional database-backed search and live folders. -* **NSWorkspace implementation**: Offers services to other applications for opening files and performing file operations. +- **Desktop**: Manages desktop icons, wallpapers, and the Dock +- **File browsing**: Navigate the filesystem with a Finder-like interface +- **.app bundle support**: Full support for application bundles as first-class citizens +- **Extensions**: Plugin system for extending functionality +- **Metadata**: Integrates with GSMetadata for file attributes -## Launching Applications -Applications are typically distributed as bundles and can be launched by double-clicking them in Workspace. +## Location -## Networking - -Network devices, such as SFTP servers, are automatically detected and can be accessed from Workspace from Go -> Network. - -### Windows SFTP server - -To make a Windows 11 computer show up there, you need to: -* Install the OpenSSH Server in Windows 11. To do so, -run PowerShell as Administrator, then run: -``` -Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0 -Start-Service sshd -Set-Service -Name sshd -StartupType Automatic -``` -* Optionally if you do not have a password set for your Windows user, set `PermitEmptyPasswords yes` in `%programdata%\ssh\sshd_config` which is `C:\ProgramData\ssh\sshd_config` usually (need to do as an Administrator) -* Install Bonjour for Windows. It comes with iTunes for Windows but can also be installed standalone from [here](https://github.com/manfred-mueller/Bonjour-Installer/releases) (NOTE: Potentially https://support.apple.com/en-us/106380 also works instead; still to be tested.) -* To advertise the sshd server on the network, run `dns-sd -R "MyWindowsBox" _sftp-ssh._tcp local 22` on the Windows machine. This Windows Service does it automatically: https://github.com/probonopd/BonjourServiceAdvertiser -* Disable the Windows firewall (TODO: Document how to just enable the needed ports) -You should now be able to see and access the Windows 11 SFTP server from Gershwin. +`/Applications/Workspace/Workspace.app` diff --git a/user/components/utilities.md b/user/components/utilities.md index ae08ea6..21140f1 100644 --- a/user/components/utilities.md +++ b/user/components/utilities.md @@ -1,6 +1,6 @@ # Utilities -Gershwin comes with the following utilities, each of which are described in this section: +Gershwin comes with the following utilities: ```{toctree} --- @@ -9,4 +9,4 @@ glob: true --- utilities/* -``` +``` diff --git a/user/getting-started.md b/user/getting-started.md index 4769a65..2e7c4c4 100644 --- a/user/getting-started.md +++ b/user/getting-started.md @@ -1,21 +1,18 @@ # Getting Started -## Installation from source +## Live ISOs -Follow https://github.com/gershwin-desktop/gershwin-build instructions. +For testing without installation, Live ISOs are available at the [Gershwin Desktop wiki](https://github.com/gershwin-desktop/gershwin-desktop/wiki). -## Live ISOs +## Installation from source -For testing, there are Live ISOs available at -* https://github.com/gershwin-desktop/gershwin-on-ghostbsd (also want: FreeBSD) -* https://github.com/gershwin-desktop/gershwin-on-arch (also want: Artix) -* https://github.com/gershwin-desktop/gershwin-on-debian (also want: Devuan) +Follow the instructions at [gershwin-build](https://github.com/gershwin-desktop/gershwin-build). ## Raspberry Pi -* https://github.com/gershwin-desktop/gershwin-desktop/wiki/Gershwin-on-Raspberry-Pi +Gershwin runs well on Raspberry Pi 5 and Raspberry Pi 500. See `developer/rpi` for details. ## Getting help -* https://github.com/orgs/gershwin-desktop/discussions -* `#gershwin` on libera.chat (be aware that answers might take a few days, so stay around or use the discussions above) +- [GitHub Discussions](https://github.com/orgs/gershwin-desktop/discussions) +- `#gershwin` on libera.chat (answers may take a few days)