Updating Docs for commit 8c770d6 made on 2025-04-05T06:35:23+00:00 from refs/heads/main by probonopd

Author: probonopd

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 2ea8f8c084aeebea80a4955dd7d6f9b7
+tags: 645f666f9bcd5a90fca523b33c5a78b7

.nojekyll

@@ -0,0 +1,5 @@
+# GitHub Pages Cache
+ 
+Nothing to see here. The contents of this branch are essentially a cache that's not intended to be viewed on github.com.
+ 
+For more information on how this documentation is built using Sphinx, Read the Docs, and GitHub Actions/Pages, see another branch in this repository.

README.md

@@ -0,0 +1,145 @@
+# Acknowledgements
+
+Grateful acknowledgement is made to the following persons and organizations.
+
+Mentions roughly in the order of first involvement with the project.
+
+## FreeBSD project
+[https://www.freebsd.org/](https://www.freebsd.org/)
+* Providing the underlying operating system
+
+## FreeBSD port maintainers
+As listed on [https://www.freshports.org/](https://www.freshports.org/)
+* Providing end user applications
+
+## Simon Peter
+__[probonopd](https://github.com/probonopd)__
+@probonopd on twitter
+* Founded the project
+* Acting as the main developer
+
+## Joe Maloney
+__[pkgdemon](https://github.com/pkgdemon)__
+malco2001 on irc (#FuryBSD)
+* Originally wrote the tools to create Live ISOs for FuryBSD
+
+## Cirrus CI
+[https://cirrus-ci.com/](https://cirrus-ci.com/)
+* Providing continuous build infrastructure
+
+## Fedor Korotkov
+__[fkorotkov](https://github.com/fkorotkov)__
+* Provided helpful support concerning all things Cirrus CI
+
+## FreeBSD Foundation
+[https://www.freebsdfoundation.org/](https://www.freebsdfoundation.org/)
+* Gave permission to use the trademarks in the 'Install FreeBSD' utility
+
+## Sławomir Wojciech Wojtczak
+__[vermaden](https://github.com/vermaden)__
+@vermaden on twitter
+* Provided helpful feedback and configuration advice
+* Configuration for tap to click and two-finger scrolling for Synaptics and Elan touchpads
+
+## Reven Martin ([CutefishOS](https://cutefishos.com/))
+__[rekols](https://github.com/rekols)__
+@revenmartin on twitter, @cutefishos on twitter
+* Originally wrote Panda Status Bar, which the hello Menu is based on
+* Originally wrote Cyber Dock, which the hello Dock is based on
+
+## Ale Rimoldi
+__[aoloe](https://github.com/aoloe)__
+@a_l_e on twitter
+* Implemented Action Search (search through menubar)
+
+## Antony jr
+__[antony-jr](https://github.com/antony-jr)__
+@antonyjr0 on twitter
+* Put Search field for Action Search in menubar
+* Integrated of 'System' menu into menubar
+
+## Keshav Bhatt
+__[keshavbhatt](https://github.com/keshavbhatt)__
+@keshavmail68 on twitter
+* Helped making 'System' menu submenus clickable
+
+## @FreeBSDHelp on twitter
+* Reached out to FreeBSD kernel developers
+
+## TheAssassin
+__[TheAssassin](https://github.com/TheAssassin)__
+* Improved documentation by providing Sphinx evangelism and ReStructuredText help
+* Helped with CMake and Qt translations
+
+## Leodanis Pozo Ramos
+__[lpozo](https://github.com/lpozo)__
+* Wrote tutorial and sample code that forms the basis for Calculator.app
+
+## Marcel Kaiser
+__[mrclksr](https://github.com/mrclksr)__
+* Wrote `initgfx` graphics hardware autoconfiguration
+
+## Graham Perrin
+__[grahamperrin](https://github.com/grahamperrin)__
+* Provided early testing and feedback
+
+## PreyK
+__[PreyK](https://github.com/PreyK)__
+* Made System menu to refresh itself automatically 
+* Fixed Menu and desktop for multi-monitor setups
+
+## Chris Moore
+__[moochris](https://github.com/moochris)__
+* Improved Filer: Added initial 'spatial mode' option (folders open in a new window) and made already-open windows come to the front rather than opening the same window multiple times
+* Made volumes show up on the desktop
+* Added menus to the desktop
+
+## Weblate
+[hosted.weblate.org](https://hosted.weblate.org/projects/hellosystem)
+* Providing infrastructure for crowd-sourced translations
+
+## Chris Rees
+__[crees](https://github.com/crees)__
+* Made it possible to use a fixed Intel GPU driver for FreeBSD 12.2 from a private package
+* Created a package for the Falkon browser that does not pull in many KDE dependencies
+* Updated required FreeBSD ports and helped writing new ports
+
+## Jordan Gordeev
+* Wrote `geom_rowr` FreeBSD kernel module to combine a read-only with a read-write device
+
+## Jesper Schmitz Mouridsen (jsmdk)
+__[jsm222](https://github.com/jsm222)__
+* Packaging helloDesktop components for FreeBSD Ports ([details](https://wiki.freebsd.org/helloDesktop))
+* Fix for the Global Menu in Chrome and Firefox
+* Added patches to Firefox and Thunderbird Ports for global menu support
+
+## Sergey Tyuryukanov
+__[s199p.wa1k9k](https://github.com/s199pwa1k9r)__
+@S199pWa1k9r on twitter
+* Packaging helloDesktop components for FreeBSD Ports on aarch64
+
+## Zoë Knox
+__[mszoek](https://github.com/mszoek)__
+@thatzoek on twitter
+* Implemented `org.freedesktop.FileManager1` API in Filer
+
+## alphamodh0
+__[alphamodh0](https://github.com/alphamodh0)__
+* Translated helloSystem to Spanish
+
+## Sebastian Birnbach
+[https://zweibruecken-ip.de/](https://zweibruecken-ip.de/)
+* Donated a Mac mini (Mid 2010) (`Macmini4,1`) to the helloSystem Hardware Test Zoo
+
+## Luna Jernberg
+__[bittin](https://github.com/bittin)__
+* Swedish translator
+
+## Framework Computer Inc
+__[FrameworkComputer](https://github.com/FrameworkComputer)__
+* Donated a Framework Mainboard (i5-1135G7) through the Developer Mainboard Program
+
+## Jérôme Ornech
+__[Hierosme](https://github.com/Hierosme)__ alias __[Tuuux](https://gitlab.com/Tuuux/)__
+* Rewrote Processes.app ([#159](https://github.com/helloSystem/Utilities/pull/159))
+* Wrote Network Utility.app

_sources/developer/acknowledgements.md.txt

@@ -0,0 +1,98 @@
+# Application Bundles
+
+helloSystem uses __application bundles__ to manage native applications. Whenever possible, application bundles are used. XDG-style `.desktop` files are considered legacy and should be avoided.
+
+## Benefits
+
+Applications shipped as application bundles can
+
+* Easily be moved around in the filesystem (relocation)
+* Easily be copied to e.g., another machine or a network share
+* Easily be copied on the local machine to get a second instance of the same application (e.g., to make changes to it while keeping the original around)
+* Easily be deleted by moving to the Trash
+* Easily be managed without the need for a package manager
+* Easily be modified (e.g., changing the icon) without any side effects to other parts of the system
+* Easily be distributed (e.g., in archives like zip files or in disk images) without the need for packaging
+* Easily be understood by switchers coming from other operating systems with similar application distribution formats
+
+## Application bundle formats
+
+### `.app` bundles
+
+helloSystem supports simplified GNUstep-style `.app` bundles.
+
+Minimal requirements:
+
+```text
+./Application.app
+./Application.app/Application <-- (link to) the executable to be launched when Application.app is double clicked
+./Application.app/Resources/Application.png <-- the application icon (png format)
+./Application.app/Resources/can-open <-- optional, MIME types the application can open, separated by `;`
+```
+
+In order to realize the full intended functionality, additional metadata may be required (such as localized application name, version, supported file formats, etc.). Possibly the GNUstep metadata format is sufficient for this.
+
+### `.AppDir` bundles
+
+helloSystem supports simplified ROX-style `.AppDir` bundles.
+
+Minimal requirements:
+
+```text
+./Application.AppDir
+./Application.AppDir/AppRun <-- (link to) the executable to be launched when Application.app is double clicked
+./Application.AppDir/.DirIcon <-- the application icon (png format)
+```
+
+In order to realize the full intended functionality, additional metadata may be required (such as localized application name, version, supported file formats, etc.). Possibly the ROX AppDir specification is not sufficient for this and may need to be amended (to be determined).
+
+### Wrappers for legacy packages
+
+helloSystem supports applications that are not shipped in bundle formats yet. These can be bridged by __wrapper bundles__, application bundles that merely launch (but do not contain) the payload application (which may be installed in traditional ways).
+
+A __desktop2app__ tool ships with helloSystem that automates the creation of such wrappers.
+
+Please note that the use of wrapper bundles is discouraged and is only available as a bridge technology for backward compatibility with existing application packages.
+
+## Building application bundles
+
+Here is a real-world example on how to build an application bundle for a Qt application written in C++ using GitHub and [Cirrus CI](https://cirrus-ci.com/):
+
+https://github.com/helloSystem/QHexEdit
+
+The application gets compiled and uploaded in a fully automated process.
+
+The resulting application bundle is provided for download in zipped form on GitHub Releases.
+
+Please see the [`.cirrus.yml`](https://github.com/helloSystem/QHexEdit/blob/main/.cirrus.yml) file for details.
+
+### Making an application load privately bundled libraries
+
+If an application is supposed to load privately bundled libraries, one must patch it so that it loads privately bundled libraries from a path relative to itself (`$ORIGIN`) rather than from `/usr/local/lib`:
+
+```console
+$ sed -i -e 's|/usr/local/lib|$ORIGIN/../lib|g' usr/local/bin/falkon
+$ ln -s usr/local/lib .
+$ rm usr/local/bin/falkon-e
+```
+
+This works because by coincidence the string `/usr/local/lib` has the exact same length as `$ORIGIN/../lib`. If this was not the case, one would need to either specify the rpath at compilation time, or use a tool such as `patchelf`.
+
+### Avoiding absolute paths
+
+For an application to be fully relocatable in the filesystem, one must take care that no absolute paths to data files (e.g., those in `/usr/share/<APPNAME>` get compiled in.
+
+In Qt applications, void [`QStringList QStandardPaths::standardLocations(QStandardPaths::AppDataLocation);`](http://doc.qt.io/qt-5/qstandardpaths.html). According to the [Qt documentation](http://doc.qt.io/qt-5/qstandardpaths.html), this resolves to `"~/.local/share/<APPNAME>", "/usr/local/share/<APPNAME>", "/usr/share/<APPNAME>"` but clearly `/usr` is not where these things are located in an `.app` bundle.
+
+Instead, use [`QString QCoreApplication::applicationDirPath()`](http://doc.qt.io/qt-5/qcoreapplication.html#applicationDirPath) and construct a _relative_ path to `../share/<APPNAME>` from there.
+
+For an example, see:
+https://github.com/KaidanIM/Kaidan/commit/da38011b55a1aa5d17764647ecd699deb4be437f
+
+## Credits
+
+Application directories and application bundles have been used by many desktop-oriented operating systems, including RISC OS, NeXTStep/OPENSTEP, Mac OS X, and various other systems. Classic Macintosh System used single-file applications that kept resources in the Resource Fork.
+
+* https://en.wikipedia.org/wiki/Application_directory
+* http://rox.sourceforge.net/desktop/AppDirs.html
+* https://en.wikipedia.org/wiki/Resource_fork

_sources/developer/application-bundles.md.txt

@@ -0,0 +1,54 @@
+# Applications
+
+Applications specifically written for helloSystem, especially Preferences and Utilities applications, should be
+* Simple to use
+* Easy to hack on
+* Open Source (2-clause BSD licensed by default, but similar permissive licenses may also be acceptable)
+* Ideally written in PyQt
+* Come as simplified `.app` bundles with no external dependencies apart from what comes with helloSystem by default on the Live ISO
+
+Some of the example applications and utilities are written in Python with PyQt. This is designed to invite (power) users to have a look at the code, start to experiment, and possibly eventually contribute. Especially when used in conjunction with the simplified `.app` bundle format and with an IDE with autocompletion, this makes for a _very_ accessible development environment with _very_ low barriers to entry. No source code to search and download, no compilers, just open the `.app` bundle and start hacking away. Tiny example applications like `Log.app` and `Calendar.app` are included that anyone should be able to understand in no time.
+
+Please see [https://github.com/learnpyqt/15-minute-apps](https://github.com/learnpyqt/15-minute-apps) for what we mean by "Simple to use" and "Easy to hack on".
+
+For an introduction to [Creating GUI applications with Python & Qt5](https://www.learnpyqt.com/pyqt5-book/) you may be interested in the book with the same name by Martin Fitzpatrick. There is also a forum at [forum.learnpyqt.com](https://forum.learnpyqt.com/).
+
+[![](https://hellosystem.github.io/docs/_static/book-pyqt5.png)](https://www.learnpyqt.com/pyqt5-book/)
+
+## Using .ui files in PyQt
+
+Using Qt Creator, you can also create and edit graphical user interfaces for __Python__ based applications using `.ui` files. These can be used in PyQt like this:
+
+```py
+#!/usr/bin/env python3
+# This Python file uses the following encoding: utf-8
+
+
+import sys
+import os
+
+
+from PyQt5.QtWidgets import QApplication, QWidget
+from PyQt5.QtCore import QFile
+from PyQt5.uic import loadUi
+
+
+class Widget(QWidget):
+    def __init__(self):
+        super(Disks, self).__init__()
+        self.load_ui()
+
+    def load_ui(self):
+        path = os.path.join(os.path.dirname(__file__), "form.ui")
+        ui_file = QFile(path)
+        ui_file.open(QFile.ReadOnly)
+        loadUi(ui_file, self)
+        ui_file.close()
+
+
+if __name__ == "__main__":
+    app = QApplication([])
+    widget = Widget()
+    widget.show()
+    sys.exit(app.exec_())
+```

_sources/developer/applications.md.txt

@@ -0,0 +1,60 @@
+# Architecture
+
+helloSystem is designed with simplicity in mind. Less, but better. This page describes key elements of the hello desktop. To begin with, everything should be welcoming for Mac users but 10x as simple.
+
+## Frameworks
+
+In order of preference:
+* PyQt
+* Qml
+* Qt
+* Kf5 components where absolutely needed
+* Everything else
+* Gtk
+
+Rationale: Most cross real-world productivity applications are written cross-platform and this often means Qt. Hence, to provide the best possible environment for those applications, we choose Qt for now. Philosophically, we would prefer to use something BSD licensed (or similar), such as FyneDesk, but in its current state it cannot yet provide the same truly native experience for existing Qt applications. (Maybe it helps to think of Qt as the "Carbon of hello", whereas something else will eventually become the "Cocoa of hello".)
+
+## 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 the hello Desktop, such as Qt and PyQt). 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.
+
+### Filer
+
+File manager that can handle (simplified) `.app` and `.AppDir` bundles
+
+### Menu
+
+Global menu bar that displays the System menu for system-wide commands (such as 'About this Computer'), and the active application's menus. It also contains a search box to search in the menus.
+
+### Dock
+
+A Dock that shows icons for running and pinned applications. (In the future it should also get an animated icon as a launching indicator for applications that are being launched but are not yet showing a window.)
+
+### `launch` command
+
+The {command}`launch` command is used to launch applications without specifying a path to them.
+
+The {command}`launch` command is expected to determine the preferred instance of an application with the given name. (The {command}`launch` command is supposed to find the _preferred_ instance, e.g., the one with the highest version, the one last put onto the system, etc.) Eventually the {command}`launch` command should also gain knowledge of which application to open a file with.
+
+Filer is supposed to launch all applications through the {command}`launch` command. Shell scripts, `.desktop` files, etc. should be written to use the {command}`launch` command rather than hardcoding paths to applications, where appropriate.
+
+If an application cannot be launched, the {command}`launch` command shall give a localized, understandable clear-text error message and offer a solution if possible; fall back to the console output of the application that could not be launched.
+When beginning to launch an application, the {command}`launch` command shall notify the Dock via some IPC mechanism (ideally something _much_ simpler than the convoluted D-Bus) about the icon and name of the application about to be launched, so that the Dock can start a launch animation until the application is showing its first window).
+
+### IPC mechanism for the desktop
+
+A very simple IPC mechanism should be introduced for the desktop components to talk to each other. A lightweight, standard publish/subscribe mechanism should be identified; _possibly_ something like MQTT (which would have the added benefit of allowing for network-wide communication). In the meantime, the use of D-Bus as a legacy technology may be acceptable (even though it is considered obscure, convoluted, and closely linked with various other Red Hat technologies.)
+
+### 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. The {command}`launch` command is responsible to determine which one to use in cases where the user did not explicitly launch a specific instance by double-clicking it.
+
+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
+
+The system should come with some commonly used utilities, such as a Terminal application, a Process Monitor application, etc. These are just regular applications inside a 'Utilities' subdirectory. It is acceptable for pre-existing applications, preferably written in Qt.
+
+### Preferences
+
+The system should come with some commonly used preference panels, such as for configuring the system language, OpenZFS Boot Environments, etc. These are just regular applications inside a 'Preferences' subdirectory. These should be super simple, "minimal viable" applications. It is expected that many will need to be written from scratch, but it is acceptable to re-use pre-existing applications, preferably written in Qt.