├── .github └── workflows │ └── main.yml ├── .gitignore ├── LICENSE ├── Makefile ├── README.md ├── _static ├── .gitkeep ├── book-pyqt5.png ├── hello_logo.png └── theme_overrides.css ├── _templates ├── .gitkeep └── epub-cover.html ├── buildDocs.sh ├── conf.py ├── developer ├── acknowledgements.md ├── application-bundles.md ├── applications.md ├── architecture.md ├── base.md ├── binary-compatibility.md ├── boot.md ├── building.md ├── contact.md ├── contributing.md ├── developer-tools.md ├── distributions.md ├── filer-context-menus.md ├── geom_rowr.md ├── graphics.md ├── linux.md ├── localization.md ├── man.md ├── menu.md ├── midi.md ├── monkey-patch.md ├── ports.md ├── rpi.md ├── specifications.md ├── tracing.md └── ux-guidelines.md ├── index.md ├── make.sh ├── requirements.txt ├── reviewer └── guide.md └── user ├── components.md ├── components ├── applications.md ├── applications │ ├── falkon.md │ └── iridium.md ├── autostart.md ├── filesystems.md ├── preferences.md ├── preferences │ ├── boot-environments.md │ ├── desktop.md │ ├── keyboard.md │ ├── sharing.md │ ├── shortcuts.md │ └── wireless-networks.md ├── system.md ├── system │ ├── dock.md │ ├── filer.md │ ├── launch.md │ └── menu.md ├── utilities.md ├── utilities │ ├── calculator.md │ ├── calendar.md │ ├── create-live-media.md │ ├── hardware-probe.md │ ├── install.md │ ├── mountarchive.md │ ├── remote-assistance.md │ ├── sticky-notes.md │ └── update.md └── windows.md ├── feedback.md ├── getting-started.md └── troubleshooting.md /.github/workflows/main.yml: -------------------------------------------------------------------------------- 1 | --- 2 | name: CI 3 | 4 | on: 5 | push: 6 | branches: [main] 7 | tags-ignore: 8 | - 'continuous' 9 | pull_request: 10 | branches: [main] 11 | 12 | # Allows you to run this workflow manually from the Actions tab 13 | workflow_dispatch: 14 | 15 | jobs: 16 | build: 17 | if: "!contains(github.event.head_commit.message, 'ci skip')" 18 | # The type of runner that the job will run on 19 | runs-on: ubuntu-latest 20 | env: 21 | G_TOKEN: ${{secrets.GITHUB_TOKEN}} 22 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 23 | 24 | steps: 25 | - uses: actions/checkout@v2 26 | 27 | - name: Build docs 28 | run: sudo -E bash -ex buildDocs.sh 29 | - name: Deploy EPUB (only when building from main branch) 30 | if: ${{ github.ref == 'refs/heads/main' }} 31 | run: | 32 | wget -c https://github.com/probonopd/uploadtool/raw/master/upload.sh 33 | bash ./upload.sh _build/epub/*.epub 34 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | __pycache__ 2 | *.py[c|o] 3 | *.swp 4 | /_build 5 | /doctrees 6 | .venv/ 7 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | BSD 2-Clause License 2 | 3 | Copyright (c) 2020, hello 4 | All rights reserved. 5 | 6 | Redistribution and use in source and binary forms, with or without 7 | modification, are permitted provided that the following conditions are met: 8 | 9 | 1. Redistributions of source code must retain the above copyright notice, this 10 | list of conditions and the following disclaimer. 11 | 12 | 2. Redistributions in binary form must reproduce the above copyright notice, 13 | this list of conditions and the following disclaimer in the documentation 14 | and/or other materials provided with the distribution. 15 | 16 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 19 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 20 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 22 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 23 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 24 | OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 25 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # Minimal makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line, and also 5 | # from the environment for the first two. 6 | SPHINXOPTS ?= 7 | SPHINXBUILD ?= sphinx-build 8 | SOURCEDIR = . 9 | BUILDDIR = _build 10 | 11 | # Put it first so that "make" without argument is like "make help". 12 | help: 13 | @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 14 | 15 | watch: 16 | sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" --ignore "*__jb*__*" 17 | 18 | .PHONY: help Makefile watch 19 | 20 | # Catch-all target: route all unknown targets to Sphinx using the new 21 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). 22 | %: Makefile 23 | @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 24 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # hello Documentation 2 | 3 | This repository builds the [documentation](https://hellosystem.github.io/docs/) for hello. 4 | 5 | It uses Sphinx, recommonmark, and GitHub Actions to produce documentation from the Markdown source files in this repository. 6 | 7 | * https://stackoverflow.com/a/62967771 8 | * https://recommonmark.readthedocs.io/en/latest/ 9 | 10 | ## Local development server 11 | 12 | Use a local development server that regenerates the output whenever the input changes: 13 | 14 | ```sh 15 | sudo pkg install -y py37-pip gmake # on FreeBSD, e.g., on helloSystem 16 | pip-3.7 install -r requirements.txt 17 | export GITHUB_REPOSITORY="helloSystem/docs" 18 | export PATH=~/.local/bin/:$PATH 19 | gmake watch 20 | ``` 21 | 22 | Now open http://127.0.0.1:8000 in a web browser. It will be regenerated and refreshed whenever one of the input files changes. 23 | 24 | ## Local output generation 25 | 26 | One can also generate documentation in various output formats locally: 27 | 28 | ```sh 29 | sudo pkg install -y py37-pip gmake # on FreeBSD, e.g., on helloSystem 30 | pip-3.7 install -r requirements.txt 31 | export GITHUB_REPOSITORY="helloSystem/docs" 32 | export PATH=~/.local/bin/:$PATH 33 | gmake html 34 | gmake epub 35 | gmake html 36 | gmake qthelp 37 | qmake # list more output formats 38 | ``` 39 | -------------------------------------------------------------------------------- /_static/.gitkeep: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/helloSystem/docs/8c770d67021f394ab65a73583b1d0423f979fac8/_static/.gitkeep -------------------------------------------------------------------------------- /_static/book-pyqt5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/helloSystem/docs/8c770d67021f394ab65a73583b1d0423f979fac8/_static/book-pyqt5.png -------------------------------------------------------------------------------- /_static/hello_logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/helloSystem/docs/8c770d67021f394ab65a73583b1d0423f979fac8/_static/hello_logo.png -------------------------------------------------------------------------------- /_static/theme_overrides.css: -------------------------------------------------------------------------------- 1 | /* -*- coding: utf-8; mode: css -*- 2 | * 3 | * Sphinx HTML theme customization: read the doc 4 | * 5 | */ 6 | 7 | /* Improve contrast and increase size for easier reading. */ 8 | 9 | body { 10 | font-family: sans-serif; 11 | color: black; 12 | font-size: 100%; 13 | } 14 | 15 | h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, h5, h6, legend { 16 | font-family: sans-serif; 17 | } 18 | 19 | .wy-menu-vertical li.current a { 20 | color: #505050; 21 | } 22 | 23 | .wy-menu-vertical li.on a, .wy-menu-vertical li.current > a { 24 | color: #303030; 25 | } 26 | 27 | div[class^="highlight"] pre { 28 | font-family: monospace; 29 | color: black; 30 | font-size: 100%; 31 | } 32 | 33 | .wy-menu-vertical { 34 | font-family: sans-serif; 35 | } 36 | 37 | .c { 38 | font-style: normal; 39 | } 40 | 41 | p { 42 | font-size: 100%; 43 | } 44 | 45 | /* Interim: Code-blocks with line nos - lines and line numbers don't line up. 46 | * see: https://github.com/rtfd/sphinx_rtd_theme/issues/419 47 | */ 48 | 49 | div[class^="highlight"] pre { 50 | line-height: normal; 51 | } 52 | .rst-content .highlight > pre { 53 | line-height: normal; 54 | } 55 | 56 | /* Keep fields from being strangely far apart due to inherited table CSS. */ 57 | .rst-content table.field-list th.field-name { 58 | padding-top: 1px; 59 | padding-bottom: 1px; 60 | } 61 | .rst-content table.field-list td.field-body { 62 | padding-top: 1px; 63 | padding-bottom: 1px; 64 | } 65 | 66 | @media screen { 67 | 68 | /* content column 69 | * 70 | * RTD theme's default is 800px as max width for the content, but we have 71 | * tables with tons of columns, which need the full width of the view-port. 72 | */ 73 | 74 | .wy-nav-content{max-width: none; } 75 | 76 | /* table: 77 | * 78 | * - Sequences of whitespace should collapse into a single whitespace. 79 | * - make the overflow auto (scrollbar if needed) 80 | * - align caption "left" ("center" is unsuitable on vast tables) 81 | */ 82 | 83 | .wy-table-responsive table td { white-space: normal; } 84 | .wy-table-responsive { overflow: auto; } 85 | .rst-content table.docutils caption { text-align: left; font-size: 100%; } 86 | 87 | /* captions: 88 | * 89 | * - captions should have 100% (not 85%) font size 90 | * - hide the permalink symbol as long as link is not hovered 91 | */ 92 | 93 | .toc-title { 94 | font-size: 150%; 95 | font-weight: bold; 96 | } 97 | 98 | caption, .wy-table caption, .rst-content table.field-list caption { 99 | font-size: 100%; 100 | } 101 | caption a.headerlink { opacity: 0; } 102 | caption a.headerlink:hover { opacity: 1; } 103 | 104 | /* Menu selection and keystrokes */ 105 | 106 | span.menuselection { 107 | color: blue; 108 | font-family: "Courier New", Courier, monospace 109 | } 110 | 111 | code.kbd, code.kbd span { 112 | color: white; 113 | background-color: darkblue; 114 | font-weight: bold; 115 | font-family: "Courier New", Courier, monospace 116 | } 117 | 118 | /* fix bottom margin of lists items */ 119 | 120 | .rst-content .section ul li:last-child, .rst-content .section ul li p:last-child { 121 | margin-bottom: 12px; 122 | } 123 | 124 | /* inline literal: drop the borderbox, padding and red color */ 125 | 126 | code, .rst-content tt, .rst-content code { 127 | color: inherit; 128 | border: none; 129 | padding: unset; 130 | background: inherit; 131 | font-size: 85%; 132 | font-family: "Courier New", Courier, monospace 133 | } 134 | 135 | .rst-content tt.literal,.rst-content tt.literal,.rst-content code.literal { 136 | color: inherit; 137 | } 138 | } 139 | -------------------------------------------------------------------------------- /_templates/.gitkeep: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/helloSystem/docs/8c770d67021f394ab65a73583b1d0423f979fac8/_templates/.gitkeep -------------------------------------------------------------------------------- /_templates/epub-cover.html: -------------------------------------------------------------------------------- 1 | {%- extends "layout.html" %} 2 | {%- block header %} 3 | 28 | {% endblock %} 29 | {%- block rootrellink %}{% endblock %} 30 | {%- block relbaritems %}{% endblock %} 31 | {%- block sidebarlogo %}{% endblock %} 32 | {%- block linktags %}{% endblock %} 33 | {%- block relbar1 %}{% endblock %} 34 | {%- block sidebar1 %}{% endblock %} 35 | {%- block sidebar2 %}{% endblock %} 36 | {%- block footer %}{% endblock %} 37 | 38 | {% block content %} 39 |
40 | Cover image 41 |

{{ title }}

42 |

Documentation

43 |
44 | {% endblock %} 45 | -------------------------------------------------------------------------------- /buildDocs.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | set -x 3 | 4 | ################################################################################ 5 | # File: buildDocs.sh 6 | # Purpose: Script that builds our documentation using sphinx and updates GitHub 7 | # Pages. This script is executed by: 8 | # .github/workflows/docs_pages_workflow.yml 9 | # 10 | # Authors: Michael Altfield 11 | # Created: 2020-07-17 12 | # Updated: 2020-07-17, further modified by probono 13 | # Version: 0.1, modified by probono 14 | ################################################################################ 15 | 16 | ################### 17 | # INSTALL DEPENDS # 18 | ################### 19 | 20 | apt-get update 21 | apt-get -y install git rsync python3-pip # qttools5-dev-tools qt5-default qt5-qmake 22 | pip3 install setuptools wheel 23 | pip3 install docutils==0.16 sphinx>=5.0.0 sphinx-autobuild sphinx_rtd_theme>=0.5.2 myst-parser # sphinxcontrib-qthelp 24 | 25 | ##################### 26 | # DECLARE VARIABLES # 27 | ##################### 28 | 29 | pwd 30 | ls -lah 31 | export SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct) 32 | 33 | ############## 34 | # BUILD DOCS # 35 | ############## 36 | 37 | # build our documentation with sphinx (see ./conf.py) 38 | # * https://www.sphinx-doc.org/en/master/usage/quickstart.html#running-the-build 39 | make clean 40 | make html 41 | make epub 42 | make qthelp 43 | # qcollectiongenerator _build/qthelp/*.qhcp 44 | # sphinx-build -b html . _build 45 | # make -C ./docs html 46 | 47 | ##################################### 48 | # Upload outputs to GitHub Releases # 49 | ##################################### 50 | 51 | rm -rf ./out/ || true 52 | mkdir -p out 53 | # cp _build/qthelp/*.qhc _build/epub/*.epub out/ 54 | wget "https://github.com/tcnksm/ghr/releases/download/v0.13.0/ghr_v0.13.0_linux_amd64.tar.gz" 55 | tar xf ghr_*.tar.gz 56 | GH_USER=$(echo "${GITHUB_REPOSITORY}" | cut -d "/" -f 1) 57 | GH_REPO=$(echo "${GITHUB_REPOSITORY}" | cut -d "/" -f 2) 58 | ./ghr_*/ghr -delete -t "${G_TOKEN}" -u "${GH_USER}" -r "${GH_REPO}" -c "${GITHUB_SHA}" continuous out/ 59 | 60 | ####################### 61 | # Update GitHub Pages # 62 | ####################### 63 | 64 | printenv 65 | 66 | git config --global user.name "${GITHUB_ACTOR}" 67 | git config --global user.email "${GITHUB_ACTOR}@users.noreply.github.com" 68 | 69 | docroot=`mktemp -d` 70 | rsync -av "./_build/html/" "${docroot}/" 71 | 72 | pushd "${docroot}" 73 | 74 | # don't bother maintaining history; just generate fresh 75 | git init 76 | git remote add deploy "https://token:${G_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" 77 | git checkout -b gh-pages 78 | 79 | # add .nojekyll to the root so that github won't 404 on content added to dirs 80 | # that start with an underscore (_), such as our "_content" dir.. 81 | touch .nojekyll 82 | 83 | # Add README 84 | cat > README.md <` get compiled in. 84 | 85 | 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/", "/usr/local/share/", "/usr/share/"` but clearly `/usr` is not where these things are located in an `.app` bundle. 86 | 87 | Instead, use [`QString QCoreApplication::applicationDirPath()`](http://doc.qt.io/qt-5/qcoreapplication.html#applicationDirPath) and construct a _relative_ path to `../share/` from there. 88 | 89 | For an example, see: 90 | https://github.com/KaidanIM/Kaidan/commit/da38011b55a1aa5d17764647ecd699deb4be437f 91 | 92 | ## Credits 93 | 94 | 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. 95 | 96 | * https://en.wikipedia.org/wiki/Application_directory 97 | * http://rox.sourceforge.net/desktop/AppDirs.html 98 | * https://en.wikipedia.org/wiki/Resource_fork 99 | -------------------------------------------------------------------------------- /developer/applications.md: -------------------------------------------------------------------------------- 1 | # Applications 2 | 3 | Applications specifically written for helloSystem, especially Preferences and Utilities applications, should be 4 | * Simple to use 5 | * Easy to hack on 6 | * Open Source (2-clause BSD licensed by default, but similar permissive licenses may also be acceptable) 7 | * Ideally written in PyQt 8 | * Come as simplified `.app` bundles with no external dependencies apart from what comes with helloSystem by default on the Live ISO 9 | 10 | 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. 11 | 12 | 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". 13 | 14 | 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/). 15 | 16 | [![](https://hellosystem.github.io/docs/_static/book-pyqt5.png)](https://www.learnpyqt.com/pyqt5-book/) 17 | 18 | ## Using .ui files in PyQt 19 | 20 | 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: 21 | 22 | ```py 23 | #!/usr/bin/env python3 24 | # This Python file uses the following encoding: utf-8 25 | 26 | 27 | import sys 28 | import os 29 | 30 | 31 | from PyQt5.QtWidgets import QApplication, QWidget 32 | from PyQt5.QtCore import QFile 33 | from PyQt5.uic import loadUi 34 | 35 | 36 | class Widget(QWidget): 37 | def __init__(self): 38 | super(Disks, self).__init__() 39 | self.load_ui() 40 | 41 | def load_ui(self): 42 | path = os.path.join(os.path.dirname(__file__), "form.ui") 43 | ui_file = QFile(path) 44 | ui_file.open(QFile.ReadOnly) 45 | loadUi(ui_file, self) 46 | ui_file.close() 47 | 48 | 49 | if __name__ == "__main__": 50 | app = QApplication([]) 51 | widget = Widget() 52 | widget.show() 53 | sys.exit(app.exec_()) 54 | ``` 55 | -------------------------------------------------------------------------------- /developer/architecture.md: -------------------------------------------------------------------------------- 1 | # Architecture 2 | 3 | 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. 4 | 5 | ## Frameworks 6 | 7 | In order of preference: 8 | * PyQt 9 | * Qml 10 | * Qt 11 | * Kf5 components where absolutely needed 12 | * Everything else 13 | * Gtk 14 | 15 | 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".) 16 | 17 | ## Desktop components 18 | 19 | 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. 20 | 21 | ### Filer 22 | 23 | File manager that can handle (simplified) `.app` and `.AppDir` bundles 24 | 25 | ### Menu 26 | 27 | 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. 28 | 29 | ### Dock 30 | 31 | 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.) 32 | 33 | ### `launch` command 34 | 35 | The {command}`launch` command is used to launch applications without specifying a path to them. 36 | 37 | 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. 38 | 39 | 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. 40 | 41 | 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. 42 | 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). 43 | 44 | ### IPC mechanism for the desktop 45 | 46 | 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.) 47 | 48 | ### Applications 49 | 50 | 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. 51 | 52 | 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. 53 | 54 | ### Utilities 55 | 56 | 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. 57 | 58 | ### Preferences 59 | 60 | 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. 61 | -------------------------------------------------------------------------------- /developer/base.md: -------------------------------------------------------------------------------- 1 | # Working with the FreeBSD base system 2 | 3 | In some situations it may be necessary to make changes to existing software that comes in the FreeBSD base system. 4 | 5 | This section describes how to make such changes using an example. 6 | 7 | ## Example 8 | 9 | Suppose you would like to make a small change to the source code of software that comes in the FreeBSD base system. 10 | 11 | Here is a real-life example on how to do that: 12 | 13 | can be fixed by changing a few lines in 14 | 15 | 16 | 17 | ## Installing the FreeBSD source code 18 | 19 | Unfortunately one has to download/update the whole FreeBSD source code, even if one just wants to make a change to one command line tool. 20 | 21 | From (or from whatever FreeBSD version you are using) download {file}`src.txz`. Then: 22 | 23 | ```console 24 | $ cd / 25 | $ tar xf ~/Downloads/src.txz 26 | $ rm ~/Downloads/src.txz 27 | ``` 28 | 29 | ## Building a command line tool without changes 30 | 31 | Build the command line tool without changes first to ensure it builds and works as expected. 32 | 33 | ```console 34 | $ cd /usr/src/usr.sbin/efivar/ 35 | $ make 36 | $ /usr/obj/usr/src/amd64.amd64/usr.sbin/efivar/efivar 37 | ``` 38 | 39 | ## Making changes 40 | 41 | Now make changes to the command line tool. 42 | 43 | ```console 44 | $ cd /usr/src/usr.sbin/efivar/ 45 | $ rm efivar.c 46 | // From https://reviews.freebsd.org/D29620 47 | $ wget "https://reviews.freebsd.org/file/data/yytb47lr5cxaijaaupeh/PHID-FILE-gihl33z7feu4dagjxjgz/usr.sbin_efivar_efivar.c" -O efivar.c 48 | $ make 49 | $ /usr/obj/usr/src/amd64.amd64/usr.sbin/efivar/efivar 50 | ``` 51 | -------------------------------------------------------------------------------- /developer/binary-compatibility.md: -------------------------------------------------------------------------------- 1 | # Binary Compatibility 2 | 3 | Binary compatibility is an important concept in software engineering. It allows applications compiled on a build system to run on user's target systems without forcing them to upgrade their entire system all the time. As the FreeBSD wiki page on binary compatibility points out, "a lot of downstream users keep systems for about 10 years and want to be able to keep running their stack on top of FreeBSD without worrying that an upgrade will break things." 4 | 5 | :::{note} 6 | This page is in draft status and needs to be reviewed by experienced FreeBSD developers. Pull requests welcome. 7 | ::: 8 | 9 | ## Application compatibility 10 | 11 | The Application Binary Interface (ABI) defines which applications can run on which systems. The two main factors in determining application compatibility are the FreeBSD version (e.g., `12.x`) and the version of packages (e.g., `quarterly`). 12 | 13 | * Applications compiled on one major version of FreeBSD are expected to run on subsequent minor versions of the same major version of FreeBSD if the packages of the dependencies on the target system are no older than on the build system. __Example:__ An application compiled on FreeBSD 12.0 is expected to run on FreeBSD 12.1 and 12.2 if the packages of the dependencies on the target system are no older than on the build system 14 | * Applications compiled on one major version of FreeBSD are expected to run on subsequent major versions of FreeBSD if compatibility libraries are installed. __Example:__ An application compiled on FreeBSD 3.2 is expected to run on FreeBSD 14 if compatibility libraries are installed. __But__ this is what happens when you try to `pkg-static add` a package built on FreeBSD 12 on a FreeBSD 13 machine: `pkg-static: wrong architecture: FreeBSD:12:amd64 instead of FreeBSD:13:amd64` - apparently `pkg-static add` does not make use of the compatibility assumption but this can be worked around by exporting, e.g., `ABI=freebsd:12:amd64`; `pkg install` does not seem to have this issue. 15 | 16 | 17 | ### Recommendation for building binary compatible applications 18 | 19 | Build on the `.0` minor version for each still-supported major version of FreeBSD, using `release_0`, `release_1`, `release_2`,... but __NOT__ `quarterly`, `latest` packages as those are moving targets which will vanish over time. 20 | 21 | This should allow the application to run on all still-supported FreeBSD releases. 22 | 23 | ## Kernel module compatibility 24 | 25 | The Kernel Binary Interface (KBI) defines which kernel extensions can run on which systems. 26 | 27 | :::{note} 28 | Section to be written. Pull requests welcome. 29 | ::: 30 | 31 | * Normally, kernel extensions compiled on one major version of FreeBSD are expected to run on subsequent minor versions of the same major version of FreeBSD. However, there are notable exceptions such as the `i915kms` package that contains the Intel GPU driver. 32 | 33 | __Note:__ The `i915kms` package that contains the Intel GPU driver breaks on 12.2-RELEASE. 34 | 35 | :::{note} 36 | Explanation to be written. Pull requests welcome. 37 | ::: 38 | 39 | ### Recommendation for building binary compatible kernel modules 40 | 41 | Build on the `.0` minor version for each still-supported major version of FreeBSD. Test whether the kernel module runs on all subsequent minr versions and build for those minor versions separately in case it does not. This should allow the kernel module to run on all still-supported FreeBSD releases. 42 | 43 | 44 | ## References 45 | 46 | * describes best practices for maintaining binary compatibility in FreeBSD 47 | * [i915kms package breaks on 12.2-RELEASE](https://forums.freebsd.org/threads/i915kms-package-breaks-on-12-2-release-workaround-build-from-ports.77501/) 48 | -------------------------------------------------------------------------------- /developer/boot.md: -------------------------------------------------------------------------------- 1 | # Boot process 2 | 3 | ## Speeding up the boot process 4 | 5 | As a desktop-centric system, helloSystem should bring up a graphical desktop as soon as possible, and delay starting up other services such as the network beyond that point. Unfortunately, in the FreeBSD default configuration this is the other way around, and the graphical desktop will only start after the network has been configured, the time has been set using NTP, etc. 6 | 7 | While it would be possible to change the order of the scripts in {file}`/etc/rc.d` and {file}`/usr/local/etc/rc.d`, those changes might get overwritten with subsequent FreeBSD or package updates. Hence, we should never edit startup scripts provided by FreeBSD or packages. 8 | 9 | Instead, we can disable the services in question so that they don't get started as part of the normal FreeBSD boot sequence, and start them later in the boot process (after the graphical session has been started) using a custom start script. 10 | 11 | :::{note} 12 | The following instructions are DANGEROUS and can potentially lead to a system that cannot boot into a graphical desktop if things go wrong. This is currently only for developers and experienced users who know how to handle such situations. Future versions of helloSystem may come with this already set up. 13 | ::: 14 | 15 | To do this, create a Boot Environment that you can roll back to in case things go wrong. 16 | 17 | In {file}`/etc/rc.conf`, set 18 | 19 | ```text 20 | defaultroute_carrier_delay="0" 21 | defaultroute_delay="0" 22 | background_dhclient="YES" 23 | ``` 24 | 25 | Then create the following {file}`/usr/local/etc/rc.d/late-start` script: 26 | 27 | ```sh 28 | #!/bin/sh 29 | 30 | # PROVIDE: late-start 31 | # REQUIRE: slim 32 | 33 | PATH=$PATH:/usr/sbin 34 | export PATH 35 | 36 | . /etc/rc.subr 37 | 38 | name="late" 39 | start_cmd="${name}_start" 40 | 41 | extra_commands="disable_early_services" 42 | disable_early_services_cmd="${name}_disable_early_services" 43 | 44 | # NOTE: devd needs to stay enabled in early boot 45 | # so that we have a working mouse pointer as soon as Xorg is started 46 | 47 | SERVICES="setup-mouse webcamd vboxservice dsbdriverd netif routing defaultroute avahi-daemon clear-tmp cupsd ntpdate smartd sshd" 48 | 49 | late_start() 50 | { 51 | service devd restart # For networking; invokes dhcpd 52 | for SERVICE in $SERVICES ; do 53 | service "$SERVICE" onestart 54 | done 55 | } 56 | 57 | late_disable_early_services() 58 | { 59 | for SERVICE in $SERVICES ; do 60 | service "$SERVICE" disable 61 | done 62 | } 63 | 64 | load_rc_config $name 65 | run_rc_command "$1" 66 | ``` 67 | 68 | Disable the services in question with 69 | 70 | ```console 71 | $ sudo chmod +x /usr/local/etc/rc.d/late-start 72 | $ sudo service late-start disable_early_services 73 | ``` 74 | 75 | Check which services are still enabled, should now be greatly reduced: 76 | 77 | ```console 78 | $ grep -r 'enable="YES"' /etc/rc.conf* 79 | /etc/rc.conf:clear_tmp_enable="YES" 80 | /etc/rc.conf:dbus_enable="YES" 81 | /etc/rc.conf:initgfx_enable="YES" 82 | /etc/rc.conf:load_acpi_enable="YES" 83 | /etc/rc.conf:slim_enable="YES" 84 | /etc/rc.conf:zfs_enable="YES" 85 | ``` 86 | 87 | Reboot. The graphical desktop (including a usable mouse pointer) should appear ~10 seconds faster, but the network will start to work only after ~10 seconds. 88 | 89 | :::{note} 90 | This starts services like sshd; you need to edit the {file}`/usr/local/etc/rc.d/late-start` script to only start the services you would like to be started. 91 | ::: 92 | 93 | ## Debugging the Live system boot process 94 | 95 | As soon as the screen becomes grey, press "s" to boot in single-user mode. The system will boot to the first stage Live system prompt: 96 | 97 | ![livefirstsingleprompt](https://user-images.githubusercontent.com/2480569/202910574-22c0e284-8717-4ae0-9489-68cc23995e1d.png) 98 | 99 | At this point, the Live system has not been made writable yet. 100 | Enter {command}`exit` to contine. The system will boot to the second stage Live system prompt: 101 | 102 | ![livesecondsingleprompt](https://user-images.githubusercontent.com/2480569/202910576-e4253133-8544-4566-8b8e-8c0895f63edd.png) 103 | 104 | At this point, the system has been made partly writable by the `init_script`. To see the messages, you can press the {kbd}`ScrLk` key on your keyboard and then use the arrow up and arrow down keys on your keyboard. Then press the {kbd}`ScrLk` key again. 105 | 106 | Hit the {kbd}`Enter` key on your keyboard. 107 | 108 | Here you can make changes to files like {file}`/usr/local/bin/start-hello`. 109 | 110 | For example, you can 111 | 112 | ```console 113 | $ mv /usr/local/bin/start-hello /usr/local/bin/start-hello.original 114 | $ ln -sf /usr/local/bin/xterm /usr/local/bin/start-hello 115 | ``` 116 | 117 | Then enter {command}`exit` to contine. The system will boot into the graphical desktop. 118 | 119 | If you have made the above changes, you can run 120 | 121 | ```console 122 | $ sh -x /usr/local/bin/start-hello.original 123 | ``` 124 | 125 | to watch {file}`start-hello.original` run in a graphical terminal. 126 | 127 | ![image](https://user-images.githubusercontent.com/2480569/202913068-5399a4fa-cefc-4ffc-ba24-9b752d6a4cff.png) 128 | 129 | Here you can see what goes wrong, if anything... and then you can create, e.g., a replacement `start-hello` script that gets loaded with Monkey Patching. 130 | 131 | ## Live system early boot process 132 | 133 | :::{note} 134 | This section describes helloSystem boot process up to 0.6.0. Starting with version 0.7.0, helloSystem will use a completely different live system boot process. This page needs to be updated accordingly. 135 | ::: 136 | 137 | The ISO contains a compressed Live system filesystem image in uzip format. This filesystem image contains the filesystem used when running the ISO. During the Live system boot process, the image needs to get mounted and needs to get turned into a read-write filesystem so that one can make changes to the running system. 138 | 139 | FreeBSD does not have a standard way to achieve this, so custom code has to be used. (The ISOs provided by the FreeBSD project do not use a compressed Live system filesystem image, and do not result in a read-write filesystem when being booted.) 140 | 141 | This is a simplified description of the boot process. There may be additional aspects which still need to be documented. 142 | 143 | 1. The bootloader gets loaded 144 | 2. The bootloader loads the kernel modules that are required for the Live system boot process as specified in {file}`overlays/boot/boot/loader.conf`. Note that the bootloader apparently is not smart enough to load the dependencies of kernel modules, so one needs to manually specify those as well. For example, `zfs.ko` up to FreeBSD 12 requires `opensolaris.ko` and from 13 onward requires `cryptodev.ko` 145 | 3. The bootloader loads the ramdisk image `ramdisk.ufs` as specified in {file}`overlays/boot/boot/loader.conf` under `mfsroot_name`. The contents of the ramdisk image are specified in `overlays/ramdisk` 146 | 4. `init.sh` from the ramdisk image gets executed as requested by {file}`overlays/boot/boot/loader.conf` under `init_script` and specified in {file}`overlays/ramdisk/init.sh`. It constructs a r/w Live filesystem tree (e.g., by replicating the system image to swap-based memdisk) at `/livecd` 147 | 5. {file}`/usr/local/bin/furybsd-init-helper` gets executed by `init.sh` in a chroot of the live filesystem, `/livecd`. It is defined in {file}`overlays/uzip/furybsd-live-settings/files/usr/local/bin/furybsd-init-helper` and deals with loading Xorg configuration based on the detected devices on PCI, and with loading virtualization-related drivers 148 | 6. The `/livecd` chroot is exited 149 | 7. `init.sh` from the ramdisk image exits 150 | 8. `etc/rc` from the ramdisk image gets executed as specified in {file}`overlays/ramdisk/etc/rc` (by what?). It tells the kernel to "reroot" (not "chroot") into the live filesystem, `/livecd` using {command}`reboot -r` 151 | 9. From here on, the boot process is the regular FreeBSD boot process with the following particularities: 152 | 10. {file}`/etc/rc.d/initgfx` detects the GPU and loads the appropriate drivers 153 | 11. {file}`/usr/local/etc/rc.d/localize` runs {file}`/usr/local/sbin/localize` which tries to determine the language of the keyboard, and by proxy, of the system. This currently supports the official Raspberry Pi keyboard and Apple computers which store the keyboard and system language in the `prev-lang:kbd` EFI variable 154 | 13. The `slim` session manager (login window) is started; when the user is logged in, it starts the script {file}`/usr/local/bin/start-hello` which starts the desktop session and sets the keyboard and system language based on the information provided by `localize` in an earlier step 155 | 156 | ### Troubleshooting the Live system early boot process 157 | 158 | * __Hangs or reboots during replicating the system image to swap-based memdisk.__ The ISO is damaged. About one out of 10 builds of the ISO have this issue. Simply build a new ISO or wait for the next ISO to be available for download 159 | * __"Cannot mount tmpfs on /dev/reroot: Operation not supported by device".__ Reason unknown. Are needed kernel modules missing? 160 | 161 | ### Seeing what the system is doing while the graphical boot screen is shown 162 | 163 | While the graphical boot screen is being displayed you can press __Ctrl+T__ to see what it is doing at that moment in time. By keeping __Ctrl+T__ __pressed down__ you can see what is going on over time. By then pressing __ScrLk__, you can use __PgUp__ and __PgDn__ to scroll around. 164 | 165 | The following information will be printed to the screen for the most relevant process based on recency and CPU usage (as decided by `proc_compare()`): 166 | 167 | * `load:` and the 1 minute load average of the system 168 | * `cmd:` and process name of the most relevant process 169 | * Process ID (PID) of that process 170 | * State of that process in `[]`. FreeBSD specific wait states are explained in https://wiki.freebsd.org/WaitChannels 171 | * Real (r), User (u), and System (s) times ([Source](https://stackoverflow.com/a/556411)) 172 | * Real is wall clock time - time from start to finish of the call. This is all elapsed time including time slices used by other processes and time the process spends blocked (for example if it is waiting for I/O to complete) 173 | * User is the amount of CPU time spent in user-mode code (outside the kernel) _within_ the process. This is only actual CPU time used in executing the process. Other processes and time the process spends blocked do not count towards this figure 174 | * Sys is the amount of CPU time spent _in the kernel for the process_. This means executing CPU time spent in system calls within the kernel, as opposed to library code, which is still running in user-space 175 | * CPU usage in percent 176 | * Resident set size (RSS), the amount of memory occupied in RAM by the most relevant process 177 | 178 | Example: `load: 0.62 cmd: sleep 1739 [nanslp] 2.97r 0.00u 0.00s 0% 2168k` 179 | 180 | ### Boot in verbose mode 181 | 182 | If you would like to observe the details of the boot process, you can start your computer in __verbose mode__. This allows you to inspect the Live system early boot process and to enter commands manually that would otherwise be executed automatically. 183 | 184 | Since helloSystem 0.8.1: To boot in verbose mode, press the {kbd}`v` key on your keyboard as soon as the screen becomes grey. 185 | 186 | Before helloSystem 0.8.1: 187 | 1. While the bootloader is running, keep the {kbd}`Backspace` key pressed until you see an `OK` prompt (alternatively, for a short time during boot, it says `Hit [Enter] to boot immediately, or any other key for command prompt.`. Press the {kbd}`Esc` key on your keyboard immediately when you see this) 188 | 2. Type `unset boot_mute` and press the {kbd}`Enter` key. This disables the graphical splash screen and results in boot messages being shown 189 | 3. Type `boot -v` and press the {kbd}`Enter` key. This results in the system being booted in verbose mode 190 | 191 | The computer should boot into a graphical desktop. 192 | 193 | ### Boot into verbose single-user mode 194 | 195 | If your computer hangs during booting, you can boot into __verbose single-user mode__. This allows advanced users, administrators, and developers to inspect the Live system early boot process and to enter commands manually that would otherwise be executed automatically. 196 | 197 | Since helloSystem 0.8.1: To boot in verbose single-user mode, press the {kbd}`s` key on your keyboard as soon as the screen becomes grey. 198 | 199 | Before helloSystem 0.8.1: 200 | 1. While the bootloader is running, keep the {kbd}`Backspace` key pressed until you see an `OK` prompt (alternatively, for a short time during boot, it says `Hit [Enter] to boot immediately, or any other key for command prompt.`. Press the {kbd}`Esc` key on your keyboard immediately when you see this) 201 | 1. Type `unset boot_mute` and press the {kbd}`Enter` key. This disables the graphical splash screen and results in boot messages being shown 202 | 1. Type `boot -v -s` and press the {kbd}`Enter` key. This results in the system being booted in verbose single-user mode 203 | 204 | The computer should boot into a text console rescue system in which parts of `init.sh` from the ramdisk image have run. 205 | 206 | :::{note} 207 | Single-user mode on the Live system currently is for developers of the Live system only. 208 | 209 | If you boot the Live system into single-user mode, then you will be dropped into a shell in the ramdisk, and you are expected to manually enter the commands required for the Live system to continue booting which would otherwise be executed by the ramdisk automatically. Specifically, you need to enter everything below the line "Running in single-user mode" in the file overlays/ramdisk/init.sh (or variants thereof). If you just exit the shell without doing this, then the system will be unable to continue booting. 210 | ::: 211 | 212 | ## Graphical desktop start process 213 | 214 | 1. The system is configured in {file}`/etc/rc.conf` to start the `slim` login manager. This also results in Xorg being started 215 | 2. `slim` is configured in {file}`/usr/local/etc/slim.conf` to start `start-hello` once the user has logged in, or if autologin has occurred 216 | 3. The {file}`/usr/local/bin/start-hello` shell script starts the various components of the helloSystem desktop 217 | 218 | ### Troubleshooting the graphical desktop start process 219 | 220 | * Login manager (`slim`) says __Failed to execute login command__. Check the {file}`/usr/local/bin/start-hello` shell script. 221 | 222 | ## Installed system boot process 223 | 224 | The boot process is the regular FreeBSD boot process. Please refer to [The FreeBSD Booting Process](https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/boot.html) for more information. 225 | 226 | ## Boot Mute 227 | 228 | Setting `boot_mute="YES"` in {file}`/boot/loader.conf` causes FreeBSD to show a boot splash screen instead of kernel messages during early boot. However, as soon as scripts from the ramdisk and init get executed, they tend to write output to the screen and manipulate it with `vidcontrol` and `conscontrol`, which results in the boot splash screen to disappear before the graphical desktop environment is started. 229 | 230 | Since helloSystem targets a broad audience including non-technical users, the following behavior is intended: 231 | * By default, show no textual boot messages 232 | * Upon specific request by the user, show boot messages (for debugging, development, and system administration) 233 | * Show a graphical splash screen during the entire boot process, all the way until the graphical desktop is started 234 | 235 | To achieve this, helloSystem uses a combination of the following techniques: 236 | 237 | * Read the `boot_mute` kernel environment variable and adjust the userland boot process accordingly 238 | * Modify {file}`/etc/rc` to run `conscontrol delete ttyv0` and redirect all of its output to `/dev/null` if `boot_mute` is set to `YES` 239 | * Modify {file}`/etc/rc.shutdown` to redirect all of its output to `/dev/null` if `boot_mute` is set to `YES` 240 | * Replace the `/sbin/vidcontrol` command by a dummy that does nothing to prevent error messages related to setting the resolution of the text-mode console from ending the boot splash early 241 | * Replace the {file}`/etc/ttys` file with an empty file to not spawn login shells on the text-mode console 242 | * Commenting out the line that ends in `/dev/console` in {file}`/etc/syslog.conf` to prevent boot from being visually interrupted by `syslog` messages 243 | * On the Live system, modify all scripts in the ramdisk to redirect all of their output to `/dev/null` if `boot_mute` is set to `YES` 244 | 245 | :::{note} 246 | Please note that if any errors are displayed on the screen during the boot process, the boot splash may still end early. In this case, the reason for the error message needs to be identified, and the message needs to be silenced. 247 | ::: 248 | 249 | To see boot messages, set `boot_mute="NO"` in {file}`/boot/loader.conf` or at the bootloader prompt. 250 | 251 | 252 | ## Modifying bootloader scripts 253 | 254 | The bootloader executes lua scripts as part of the boot process. This is not documented extensively in the FreeBSD documentation. 255 | 256 | To work on the lua scripts, it is useful to 257 | * Use VirtualBox 258 | * Install helloSystem to a virtual hard disk 259 | * In the installed system, edit `/boot/loader.conf` to contain `beastie_disable=NO` and increase the timeout 260 | 261 | Possibly there is also a way to use a lua interpreter on the booted system to work on and debug the lua scripts, but this is currently unknown. The following does not seem to work: 262 | 263 | ``` 264 | % lua54 ./loader.lua 265 | lua54: ./core.lua:447: attempt to index a nil value (global 'loader') 266 | stack traceback: 267 | ./core.lua:447: in field 'isSystem386' 268 | ./core.lua:56: in local 'recordDefaults' 269 | ./core.lua:525: in main chunk 270 | [C]: in function 'require' 271 | ./cli.lua:31: in main chunk 272 | [C]: in function 'require' 273 | ./loader.lua:36: in main chunk 274 | [C]: in ? 275 | ``` 276 | 277 | The `/boot` directory also contains files referring to 4th, those are all unused, misleading, and can be removed. Besides files with `4th` in their name this also includes files ending in `.rc`. 278 | 279 | ``` 280 | mount -uw / 281 | cd /boot 282 | find . -name '*4th*' -exec rm {} \; 283 | rm *.rc 284 | ``` 285 | 286 | Removing the misleading files makes it easier to see which code actually gets executed. All the scripting is essentially happening in `/boot/lua`. 287 | 288 | One can then edit the scripts in `/boot/lua`, and boot the virtual machine quickly into single user mode, make edits, and repeat. 289 | 290 | It seems that `/boot/lua/loader.lua` is the entry point that is hardcoded into the bootloader. 291 | 292 | So if we would like to run a "hello world", we would need to place it at that path. 293 | 294 | `/boot/lua/loader.lua` includes other lua files, e.g., `local core = require("core")`. 295 | 296 | `/boot/lua/core.lua` contains the following function: 297 | 298 | ``` 299 | function core.isMenuSkipped() 300 | return string.lower(loader.getenv("beastie_disable") or "") == "yes" 301 | end 302 | ``` 303 | 304 | `/boot/lua/loader.lua` uses this function to display the boot menu if `beastie_disable` is not set: 305 | 306 | ``` 307 | if not core.isMenuSkipped() then 308 | require("menu").run() 309 | else 310 | -- Load kernel/modules before we go 311 | config.loadelf() 312 | end 313 | ``` 314 | 315 | Directly above this, there is 316 | 317 | ``` 318 | try_include("local") 319 | ``` 320 | 321 | which seems to suggest that we can hook in our own code there by creating a new file `/boot/lua/local.lua` with our custom code: 322 | 323 | https://github.com/helloSystem/ISO/blob/experimental/overlays/boot/boot/lua/local.lua 324 | 325 | * https://man.freebsd.org/cgi/man.cgi?query=core.lua documents the functions in `core.lua` 326 | * https://man.freebsd.org/cgi/man.cgi?query=menu.lua&sektion=8 documents `menu.lua`, including an example for how to replace the default boot menu with a simple boot menu, and en example for how to add another option to the default FreeBSD welcome menu 327 | 328 | This allows us to 329 | * Load the kernel and modules without showing text on screen 330 | * Boot in verbose mode if the `V` key is pressed 331 | * Boot in single user mode if the `S` key is pressed 332 | * Show the FreeBSD bootloader menu if backspace is pressed 333 | * Adjust colors for verbose and single user boot 334 | 335 | The lua environment in the FreeBSD bootloader has some functions starting with `loader.` that seem to be undocumented, but we can list them by looking at the source code: 336 | 337 | * `loader.command()` 338 | * `loader.perform()` 339 | * `loader.command_error()` 340 | * `loader.interpret()` 341 | * `loader.parse()` 342 | * `loader.getchar()` 343 | * `loader.ischar()` 344 | * `loader.gets()` 345 | * `loader.time()` 346 | * `loader.delay()` 347 | * `loader.getenv()` 348 | * `loader.setenv()` 349 | * `loader.unsetenv()` 350 | * `loader.printc()` 351 | * `loader.openfile()` 352 | * `loader.closefile()` 353 | * `loader.readfile()` 354 | * `loader.writefile()` 355 | * `loader.term_putimage()` 356 | * `loader.fb_putimage()` 357 | * `loader.fb_setpixel()` 358 | * `loader.fb_line()` 359 | * `loader.fb_bezier()` 360 | * `loader.fb_drawrect()` 361 | * `loader.term_drawrect()` 362 | 363 | This list was generated on a system on which the FreeBSD source code is installed in `/usr/src` using the following command: 364 | 365 | ``` 366 | grep -r '^lua_' /usr/src/stand/liblua/*.c | cut -d ":" -f 2 | sed -e 's|lua_|loader.|g' | sed -e 's|loader.State \*L||g' | sed -e 's|^|* \`|g' | sed -e 's|)|)\`|g' 367 | ``` 368 | -------------------------------------------------------------------------------- /developer/building.md: -------------------------------------------------------------------------------- 1 | # Building the Live ISO 2 | 3 | helloSystem get assembled from upstream FreeBSD components, components in the FreeBSD packages system, and custom components from the helloSystem repositories. 4 | 5 | helloSystem is not a derivative (fork) of FreeBSD (like e.g., GhostBSD), but strives to be "real FreeBSD" as far as possible. Hence, helloSystem does not build all source code, but relies on binaries provided by FreeBSD wherever possible. 6 | 7 | helloSystem is distributed as an installable Live ISO file. This file gets built by the [hello Live ISO builder](https://github.com/helloSystem/ISO). 8 | 9 | Continuous builds of the ISO get produced automatically on a continuous integration (CI) system for each git commit. 10 | 11 | However, it is also possible to build the ISO locally, which is especially handy for testing and development. 12 | 13 | ## System requirements for building 14 | 15 | * A FreeBSD or helloSystem installed on the computer. The FreeBSD version needs to match the FreeBSD version of the helloSystem ISO being built (e.g., `13.2-RELEASE`) 16 | * 2 GHz dual core processor 17 | * 4 GiB RAM (system memory) 18 | * 50 GB of hard-drive space 19 | * Either a CD-RW/DVD-RW drive or a USB port for writing the Live media 20 | * A fast internet connection 21 | 22 | ## Building the Live ISO 23 | 24 | ```console 25 | $ sudo pkg install -y pkg git zsync wget bash zip devel/py-xdg librsvg2 ca_root_nss 26 | $ git clone https://github.com/helloSystem/ISO 27 | $ cd ISO 28 | $ sudo ./build.sh hello 29 | ``` 30 | 31 | The resulting Live ISO will be located at {file}`/usr/local/furybsd/iso/`. 32 | 33 | ## Writing Live Media to USB drive 34 | 35 | ```console 36 | $ sudo dd if=/usr/local/furybsd/iso/FuryBSD-12.1-XFCE.iso of=/dev/daX bs=4m status=progress 37 | ``` 38 | 39 | Replace `daX` with the respective device name. 40 | 41 | :::{warning} 42 | This will overwrite the entire contents of the selected device. Take extra caution when determining the device name. 43 | 44 | This operation cannot be undone. 45 | ::: 46 | 47 | For end users, there is the __Create Live Media__ application that can conveniently download and write Live Media with a graphical user interface. 48 | 49 | ## Burning Live Media to DVD 50 | 51 | You can use the `cdrecord` command line tool to burn Live Media to DVD. 52 | 53 | ```console 54 | # pkg install cdrtools 55 | # cdrecord /usr/local/furybsd/iso/.iso 56 | ``` 57 | 58 | ## Customizing the Live ISO 59 | 60 | helloSystem is built in a way that makes it trivially easy to apply your own changes to it. 61 | 62 | ### Different desktop environments 63 | 64 | Simply replace `hello` with the name of one of the supported desktop environments, such as 65 | 66 | * cinnamon 67 | * gnome 68 | * kde 69 | * openbox 70 | * xfce 71 | 72 | While the resulting image will be built on the same infrastructure, those will not be helloSystem builds and are not supported by the project. Still, the community may find them useful. 73 | 74 | ### Customizing the set of packages 75 | 76 | To add or remove packages, edit `settings/packages.` and rebuild the image. Substitute `` with `hello` or one of the desktop environments mentioned above. 77 | 78 | ### Customizing configuration 79 | 80 | Configuration is applied using _transient packages_ that get generated on-the-fly from the contents of the `overlays/` directory. 81 | 82 | * Overlays for the boot disk are stored in `overlays/boot` 83 | * Overlays for the initial ramdisk are stored in `overlays/ramdisk` 84 | * Overlays for the main filesystem are stored in `overlays/uzip//files/`. Note that to be included in a build, the overlay called `` must be listed in `settings/overlays.`. Substitute `` with `hello` or one of the desktop environments mentioned above. 85 | 86 | For example, a file that is supposed to appear in {file}`/usr/local/bin/app` on the main filesystem could be stored in {file}`overlays/uzip/hello/files/usr/local/bin/app`. 87 | 88 | ### Customizing the build script 89 | 90 | If a file called {file}`settings/script.` exists, then it will be executed during the build. Substitute `` with `hello` or one of the desktop environments mentioned above. For building helloSystem, {file}`settings/script.hello` performs actions such as installing applications that are not coming from FreeBSD packages, setting the wallpaper, installing fonts that are not coming from FreeBSD, and so on. 91 | 92 | All desktop-specific build steps should go into this file. 93 | -------------------------------------------------------------------------------- /developer/contact.md: -------------------------------------------------------------------------------- 1 | # Contact 2 | 3 | ## Discussions 4 | 5 | The helloSystem [Discussions](https://github.com/helloSystem/hello/discussions/) forum is a great place to interact with helloSystem users and developers. If you have questions, feel free to ask in "Q&A". If you are running helloSystem, we'd be happy to hear from you in the "Show and tell" section. 6 | 7 | ## Chat 8 | 9 | You can also meet other helloSystem users and developers at [`#helloSystem:matrix.org`](https://matrix.to/#/#helloSystem:matrix.org) from any Matrix client (such as the Element web-based Matrix client). This Matrix channel is bridged to the IRC channel #helloSystem on irc.libera.chat. Joining via Matrix has the advantage that you will see responses that you may have received while you were offline. So after asking a question, you can come back in a day or so to see if there were any responses. 10 | 11 | In any case, _please stay in the channel for a few days_ and do not expect to receive answers immediately, since we are all volunteers and come by only once in a while. 12 | -------------------------------------------------------------------------------- /developer/contributing.md: -------------------------------------------------------------------------------- 1 | # Contributing 2 | 3 | If you have found this page, chances are that you are considering to to contribute to this project. 4 | 5 | Awesome! 6 | 7 | This is a small, purely volunteer-driven project, so your contributions are _highly_ welcome. 8 | 9 | ## How to get started? 10 | 11 | * Download an experimental live ISO from https://github.com/helloSystem/ISO/releases 12 | * Look through the GitHub Issues sections of the projects within https://github.com/helloSystem/ 13 | * A great way to get started is to comment on some GitHub issues. Also feel free to open new ones. We use GitHub Issues as a means of discussion and keeping track of everything, so don't hesitate to use them. General topics not related to any particular component go to https://github.com/helloSystem/hello/issues 14 | * Especially have a look at issues marked with ![](https://user-images.githubusercontent.com/2480569/97901371-64b8ad80-1d3c-11eb-8282-0bfdcd3fe512.png). Here your contributions would be especially helpful, but of course your contributions to other tickets are more than welcome, too 15 | * There is a liberal amount of `FIXME` and `TODO` in the source code. Reducing the number of those is always highly welcome 16 | 17 | ## Our project values 18 | 19 | * Please see https://github.com/helloSystem/hello for the general philosophy of the project 20 | * Always keep in mind that our philosophy is "simple > complicated", "less, but better" 21 | * We prefer small pull requests that change one thing each, rather than large ones that do many things at once 22 | * Please avoid complex code structures that require deep C++ knowledge (e.g., avoid subclassing, pointer arithmetic,... where possible) 23 | * We appreciate code with comments that explain why we are doing something 24 | * Our policy is to merge PRs liberally but roll back changes that cause breakage quickly. `master` must always build and not crash 25 | 26 | ## Areas we especially need help with 27 | 28 | Here is what we need help with: [Issues flagged with help-wanted](https://github.com/search?q=org%3AhelloSystem+is%3Aissue+is%3Aopen+label%3A%22help+wanted%22), and of course other contributions are also welcome. 29 | 30 | Maybe you'd like to look into one of these: [Issues flagged with good-first-issue](https://github.com/search?q=org%3AhelloSystem+is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22&type=). 31 | -------------------------------------------------------------------------------- /developer/developer-tools.md: -------------------------------------------------------------------------------- 1 | # Developer Tools 2 | 3 | Starting with helloSystem 0.7.0, compilers, headers, `.o` files and other files for developers are not shipped on the helloSystem Live ISO by default in order to reduce the ISO size. You need to install the Developer Tools from `developer.img` which is a separate download from the same location you obtained the Live ISO (e.g., for 0.7.0, this is https://github.com/helloSystem/ISO/releases/tag/r0.7.0). 4 | 5 | The __Developer__ folder in the __Applications__ folder contains useful development tools for use with helloSystem. 6 | 7 | * __PyCharm CE__: A powerful integrated development environment (IDE) for the Python language which is used for many of the utilities and preferences applications in helloSystem 8 | * __Qt Creator__: The integrated development environment (IDE) for Qt-based applications, such as Menu, Dock, and Filer. Includes graphical user interface editors for QtWidgets-based user interfaces (such as Menu and Filer) using `.ui` files and for Qml-based user interfaces (such as Dock) using `.qml` files. The user interfaces generated in Qt Creator can be used in Qt application written in C++ or Python 9 | * __LiteIDE__: An integrated development environment (IDE) for the Go language. Go is recommended for long-running processes such as servers and for processes with parallelism 10 | * __Zeal__: A browser for documentation sets, also known as "docsets". Docsets can be downloaded from within the application and are available for many languages and environments, including Python, Qt, and Go. 11 | 12 | To minimize the initial download size of the helloSystem image, the applications in the Developer folder need to be downloaded prior to first use. You will be guided through this automatic process when you launch these applications for the first time. After the applications have been downloaded, you can use them without an active network connection. 13 | -------------------------------------------------------------------------------- /developer/distributions.md: -------------------------------------------------------------------------------- 1 | # Note to distributions 2 | 3 | helloSystem is designed, developed, and tested as an integrated operating system. It is not a desktop environment designed to run on various operating systems or distributions. 4 | 5 | Focusing on building one coherent operating system greatly simplifies the code, the development and testing process, and ultimately increases quality. 6 | 7 | __Please do not try to include helloSystem in third-party distributions.__ While you are free to use components from helloSystem for your own projects as far as their respective licenses permit, please be aware that we may not always be interested in contributions that increase portability, especially if they would increase complexity significantly. 8 | 9 | __Please do not call your derivatives "hello" or "helloSystem"__. In order to keep support and maintenance burden low, please give clearly distinguishable names to your derivatives. 10 | 11 | You may want to include the desktop components of helloSystem, the **helloDesktop** "Desktop Environment" (collection of individual components, really). 12 | 13 | For example, work is being done to bring the helloDesktop components to FreeBSD: . But please note that "FreeBSD with helloDesktop" is not the same as helloSystem. 14 | 15 | Please do not hesitate to contact the team if you have questions regarding this policy. 16 | -------------------------------------------------------------------------------- /developer/geom_rowr.md: -------------------------------------------------------------------------------- 1 | # geom_rowr kernel module 2 | 3 | The `geom_rowr` kernel module for FreeBSD makes a read-only device writable by combining it with a read-write device. 4 | 5 | :::{note} 6 | This kernel module is currently under development and is being tested for adoption in helloSystem. 7 | ::: 8 | 9 | ## Use case 10 | 11 | When creating a Live ISO, we want to use a read-only filesystem (that can reside on a medium that is physically read-only, such as a DVD) but make it appear to the system as if it was read-write (since some parts of the system may not work on a read-only system). 12 | 13 | ## Theory of operation 14 | 15 | `geom_rowr` is a FreeBSD kernel module using the [GEOM Modular Disk Transformation Framework](https://docs.freebsd.org/en/books/handbook/geom.html). It allows you to take a read-only device (e.g. a DVD) and combine it with a read-write device (e.g., a swap-backed `md` memory disk) to get a new device that contains the data from the read-only device but is writable. 16 | 17 | It is designed to work with any filesystem, including ZFS. It is compatible with `geom_uzip` so the read-only filesystem can be compressed with uzip. 18 | 19 | The principle of operation is as follows: 20 | 21 | * Reading a sector from the combined device reads it from the read-only device. Writing a sector writes it to the read-write device 22 | * After a sector is written, future reads of that sector are satisfied from the read-write device as it contains the latest version of the sector's contents 23 | 24 | As a result, immediately after creating the combined device, it appears to contain all the data from the read-only device. This means zero wait time for the user. 25 | 26 | ## Test 27 | 28 | Execute the following commands as root: 29 | 30 | ```console 31 | // Prepare filesystem image 32 | # dd if=/dev/zero of=test.img bs=1M count=512 33 | # mdconfig -a -t vnode -f test.img -u 9 34 | # newfs /dev/md9 35 | # mount /dev/md9 /mnt 36 | // Populate the filesystem 37 | # cp -R /boot/ /mnt 38 | # umount /mnt 39 | # mdconfig -d -u 9 40 | 41 | // Load kernel module 42 | # kldload ./geom_rowr.ko 43 | // prepare the read-only device md0 44 | # mdconfig -a -t vnode -o readonly -f test.img -u 0 45 | // prepare the read-write device md1 46 | # mdconfig -a -t swap -s 512M -u 1 47 | // Make sure the geom(8) tool will find the .so 48 | # cp geom_rowr.so /lib/geom 49 | // Create the new device that combines md0 and md1 50 | # geom rowr create rowr0 md0 md1 51 | # mount /dev/rowr0 /mnt 52 | 53 | // See that the files are already there 54 | # ls /mnt 55 | // make changes to the filesystem to see that it is read-write 56 | # mv /mnt/*.4th /mnt/lua; rm /mnt/pxeboot 57 | ``` 58 | 59 | ## Use in the Live ISO boot process 60 | 61 | This can be used for a Live ISO like this: 62 | 63 | * On the ISO, there is a small `ramdisk.ufs` that contains the logic to mount the main filesystem using `geom_rowr` 64 | * On the ISO, there is also the main filesystem `system.ufs` which is a UFS image compressed with `geom_uzip` 65 | * At boot time, the code in the ramdisk creates a r/w swap-backed `md` device with the same size as the main r/o filesystem image, mounts it together with the main filesystem using `geom_rowr`, and chroots into the combined r/w filesystem. From there, the boot process continues as usual 66 | 67 | ## Caveats 68 | 69 | ### Device size 70 | 71 | * The r/o image must have as much free space as you would like to have on the combined device. This can be achieved, e.g., like this: `makefs -b 20% -f 20% /usr/local/furybsd/cdroot/data/system.ufs /usr/local/furybsd/uzip` which will add an extra 20% of free space to the main filesystem image 72 | * The free space is compressed very efficiently when the image is compressed with `geom_uzip`. This can be achieved, e.g., like this: `mkuzip -o /usr/local/furybsd/cdroot/data/system.uzip /usr/local/furybsd/cdroot/data/system.ufs` 73 | * The uncompressed r/o image and the r/w device need to be the exact same size in bytes. Assuming variable `${x}` holds the size of the uncompressed r/o image in bytes, a matching r/w device with the same size in bytes can be created using `mdconfig -a -t swap -s ${x}b -u 2` (note the `b` suffix to the `-s` option). If this is not done correctly, we get the `geom: mediasize mismatch` error 74 | 75 | You can have an [md(4)](https://www.freebsd.org/cgi/man.cgi?md%284%29) device be of size 3GB without it consuming 3GB of RAM. 76 | This is valid for vnode-backed md devices, swap-backed md devices and malloc-backed when the `reserve` option to [mdconfig(8)](https://www.freebsd.org/cgi/man.cgi?mdconfig(8)) isn't used. 77 | 78 | A swap-backed `md` device consumes close to zero memory when created and grows its memory use the more you write to it. 79 | 80 | ### Reroot 81 | 82 | Because `reroot` cannot be made to work with `geom_rowr` at this time, we need to use `chroot`. 83 | 84 | When using `chroot`, some kernel modules that load firmware (e.g., for Intel WLAN drivers) fail to load the firmware if the places where kernel modules are located - {file}`/boot/kernel` and {file}`/boot/modules` - will look differently inside vs. outside the chroot. 85 | 86 | This can be fixed. 87 | 88 | Recommended way (to be tested): 89 | 90 | Provided that `ramdisk.ufs` does not contain {file}`/boot`, create a symlink on `ramdisk.ufs` from {file}`/boot` to {file}`/sysroot/boot`. The symlink can be made at image creation time or by a script that runs at runtime. This combined with the *default* `kern.module_path` should be enough to create a common view between the kernel and chrooted userland utilities. The places where kernel modules are located - {file}`/boot/kernel` and {file}`/boot/modules` - will look the same inside and outside of the chroot. 91 | 92 | Alternative way (known to work): 93 | 94 | ```console 95 | # mkdir -p /sysroot/sysroot/boot # Needed? 96 | # mount -t nullfs /sysroot/boot /sysroot/sysroot/boot # Needed? 97 | 98 | # echo "==> Set kernel module path for chroot" 99 | # sysctl kern.module_path=/sysroot/boot/kernel 100 | ``` 101 | 102 | ### ZFS 103 | 104 | With ZFS there is a problem unrelated to the `geom_rowr` code. When ZFS performs discovery of devices which are part of a zpool, the read-only device could be found before the combined rowr device which leads to inability to import the pool read-write. 105 | 106 | (TODO: Insert tested workaround here) 107 | 108 | ## License 109 | 110 | ```text 111 | geom_rowr.ko, geom_rowr.so: Copyright (c) 2021, Jordan Gordeev 112 | ``` 113 | 114 | The author states that once the code reaches a certain level of maturity, it will be published under the license used by the FreeBSD project. 115 | -------------------------------------------------------------------------------- /developer/graphics.md: -------------------------------------------------------------------------------- 1 | # Graphics hardware autoconfiguration 2 | 3 | helloSystem uses `initgfx` for the automatic configuration of the graphics hardware in your computer. 4 | 5 | ## Theory of operation 6 | 7 | `initgfx` consists of the following files and directories: 8 | 9 | ```text 10 | /etc/rc.d/initgfx 11 | /etc/initgfx_device.db 12 | /etc/initgfx_xorg.cfg 13 | /usr/local/nvidia// 14 | /usr/local/etc/X11/xorg.conf.d/ # defined by path_xorg_cfg_dir 15 | ``` 16 | 17 | `initgfx` calculates a config ID which is a MD5 checksum of the output of `sysctl 18 | dev.vgapci | sort`. If the file `/var/initgfx_config.id` exists, check if 19 | its content matches the config ID. If that is the case, load the modules 20 | set via the `rc.conf` variable `initgfx_kmods`, and exit. If the file 21 | `/var/initgfx_config.id` does not exist, or its content does not match the 22 | config ID, try to auto-detect the accelerated graphics driver. Use `xinit` 23 | to test if the X server starts, change `initgfx_kmods`, write a new xorg 24 | config file, and save the new config ID if the test was successful. 25 | Otherwise, as a fallback, write a xorg config file for the VESA or SCFB 26 | driver depending on whether the system was booted via BIOS or EFI. 27 | 28 | [Source](https://github.com/nomadbsd/NomadBSD/commit/a346f134aaca1cdc164346f63808abdb4d8919e3) 29 | 30 | If everything goes well, then after running `sudo sysctl initgfx start` you should have (example: Nvidia): 31 | 32 | ```console 33 | $ cat /usr/local/etc/X11/xorg.conf.d/00-video-initgfx.conf 34 | Section "Device" 35 | Identifier "NVIDIA CARD" 36 | VendorName "NVIDIA Corporation" 37 | Driver "nvidia" 38 | BusID "PCI:1:0:0" 39 | EndSection 40 | ``` 41 | 42 | ## Disabling the graphics driver menu 43 | 44 | If you want to disable the graphics driver menu, add 45 | 46 | `initgfx_menu="NO"` to `/etc/rc.conf`. 47 | 48 | By default, initgfx will try autodetection, but you can instead define a default driver to use by setting `initgfx_default` to `scfb` or `vesa` in `/etc/rc.conf`. 49 | 50 | 51 | ## Disabling the automatic graphics driver setup 52 | 53 | If you want to create your own graphics driver settings, you can disable initgfx by adding 54 | 55 | `initgfx_enable="NO"` to `/etc/rc.conf`. 56 | 57 | If you would like to temporarily disable the automatic graphics driver setup and use a failsafe non-accelerated driver (VESA or SCFB), then enter `set initgfx.detect.disable=1` followed by `boot` at the bootloader prompt. This can be useful e.g., in cases where the automatically detected graphics driver does not work properly on the Live system. 58 | 59 | ## Troubleshooting 60 | 61 | If applications that are using OpenGL crash on Nvidia systems, then it may be that the Nvidia driver was correctly loaded but the wrong Xorg configuration has been loaded, not actually using the Nvidia driver. This can happen when initgfx writes the dynamically generated Xorg configuration to `path_xorg_cfg_dir` (which points to `/usr/local/etc/X11/xorg.conf.d/` by default) but other files have been placed by other packages or the user into, e.g., `/etc/X11/xorg.conf.d`. You can verify which Xorg configuration directory was used by Xorg with `cat /var/log/Xorg.0.log | grep Using.config`. Seemingly Xorg cannot combine configuration stored in multiple `xorg.conf.d` directories. 62 | 63 | ## Nvidia drivers 64 | 65 | 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. 66 | 67 | To check this: 68 | 69 | ```console 70 | $ cat /etc/rc.conf | grep initgfx_kmods 71 | initgfx_kmods="/usr/local/nvidia/390/boot/modules/nvidia.ko /usr/local/nvidia/390/boot/modules/nvidia-modeset.ko" 72 | ``` 73 | -------------------------------------------------------------------------------- /developer/linux.md: -------------------------------------------------------------------------------- 1 | # Building on Linux 2 | 3 | helloSystem is designed for use with helloSystem, which is based on FreeBSD. 4 | 5 | However, developers may want to verify that the code is reasonably platform independent by building on Linux from time to time. 6 | 7 | :::{note} 8 | That the code build does not necessarily mean that it works properly on Linux or that all features are implemented for Linux. 9 | ::: 10 | 11 | ## Building in a chroot on a FreeBSD host 12 | 13 | To verify that the code builds on Linux without needing a different development machine, one can use an [Alpine Linux](https://alpinelinux.org/) chroot in FreeBSD. 14 | 15 | Beginning with build 0H165, helloSystem ships with an [alpine rc.d script](https://github.com/helloSystem/ISO/blob/experimental/overlays/uzip/hello/files/usr/local/etc/rc.d/alpine). 16 | When started for the first time, this downloads a minimal root filesystem. 17 | 18 | ```console 19 | $ sudo service linux stop 20 | $ sudo service debian stop 21 | $ sudo service alpine onestart 22 | $ sudo chroot /compat/alpine /bin/sh 23 | ``` 24 | 25 | In the chroot, build the essential helloSystem components 26 | 27 | ```console 28 | // launch, open, and other essential command line tools that are required 29 | $ git clone https://github.com/helloSystem/launch 30 | $ mkdir -p launch/build 31 | $ cd launch/build 32 | $ grep ^apk ../README.md | sh 33 | $ cmake .. 34 | $ sudo make -j $(nproc) install 35 | $ cd ../../ 36 | 37 | // Menu 38 | $ git clone https://github.com/helloSystem/Menu 39 | $ mkdir -p Menu/build 40 | $ cd Menu/build 41 | $ grep ^apk ../README.md | sh 42 | $ cmake .. 43 | $ sudo make -j $(nproc) install 44 | $ cd ../../ 45 | 46 | // Filer 47 | $ git clone https://github.com/helloSystem/Filer 48 | $ mkdir -p Filer/build 49 | $ cd Filer/build 50 | $ grep ^apk ../README.md | sh 51 | $ cmake .. 52 | $ sudo make -j $(nproc) install 53 | $ cd ../../ 54 | ``` 55 | 56 | After you are done, 57 | 58 | ```console 59 | $ sudo service alpine onestop 60 | ``` 61 | 62 | :::{note} 63 | If the compiler crashes, make sure that {file}`/usr/bin/clang++` is being used rather than {file}`/usr/bin/c++`. This can be edited in CMakeCache.txt. 64 | ::: 65 | 66 | ## Running helloDesktop on Linux 67 | 68 | Run Alpine Linux, e.g., in VirtualBox on helloSystem, or on real hardware. 69 | 70 | * Download ISO from https://alpinelinux.org/downloads/, "Standard" 71 | * User `root`, no password is the default 72 | * Install to to a hard disk using the `setup-alpine` command, need to use a classic ("sys mode") installation 73 | * Enable community repo by `sed -i -e 's|^#||g' /etc/apk/repositories` 74 | * Install KDE Plasma using `setup-desktop`; set up a user 75 | * `rc-update add sddm` and `rc-service sddm start` 76 | * Log into a KDE Plasma session on Alpine Linux. 77 | :::{important} 78 | Select X11 session. Wayland doesn't work smoothly 79 | ::: 80 | * Optionally, install VirtualBox related guest packages using `apk search` and `apk add` 81 | * `sudo su` to become root (there is no `sudo` configured on Alpine Linux by default) 82 | * Build and `make install` the three core components of helloDesktop (launch, Menu, and Filer) as above 83 | * From within the running KDE Plasma session, you can switch to the minimal helloDesktop with 84 | 85 | ```sh 86 | #!/bin/sh 87 | 88 | launch Menu & 89 | sleep 1 90 | launch Filer & 91 | killall plasmashell 92 | ``` 93 | 94 | Menu shoud work including full text search in the filesystem. 95 | 96 | The result will look somewhat like this: 97 | 98 | ![Screenshot](https://user-images.githubusercontent.com/2480569/200421869-96f81c37-0785-4416-ae43-bee920dd6a3e.png) 99 | 100 | :::{note} 101 | That the code runs does not necessarily mean that it works properly on Linux or that all features are implemented for Linux. Please keep in mind that for the best desktop experience, you should be using helloSystem which helloDesktop has been designed for. 102 | ::: 103 | 104 | ## Building and running helloDesktop on Raspberry Pi 105 | 106 | Loosely follow (not all commands seem to be working exactly as written anymore), but also create "Linux Swap" partition. Alternatively, in the running Alpine Linux system 107 | 108 | ```console 109 | # fallocate -l 8G /swapfile 110 | # mkswap /swapfile 111 | # swapon /swapfile 112 | ``` 113 | 114 | to have enough RAM or else the compilation will be killed (at least on the 1GB and less RAM models). 115 | -------------------------------------------------------------------------------- /developer/localization.md: -------------------------------------------------------------------------------- 1 | # Localization 2 | 3 | helloSystem is localized on [Hosted Weblate](https://hosted.weblate.org/projects/hellosystem/). 4 | 5 | [![Translation status](https://hosted.weblate.org/widgets/hellosystem/-/multi-auto.svg)](https://hosted.weblate.org/engage/hellosystem/) 6 | 7 | ## Contributing translations 8 | 9 | helloSystem is translated into many languages by volunteers all over the world. 10 | 11 | Translation happens on [Weblate](https://hosted.weblate.org/engage/hellosystem/). Everyone can contribute! Be sure to use the "Automatic suggestions" button which suggests translations from Deepl, Google Translate, Microsoft Translator, and various open source projects. This reduces the work to picking the most appropriate translation in many cases. 12 | 13 | ## Making strings available for translation 14 | 15 | ### Qt 16 | 17 | Follow the best practices for internationalization of Qt projects. To be documented. 18 | 19 | ### Python 20 | 21 | helloSystem uses `tstranslator.py` to translate applications using Qt `.ts` files without the need for compilation. To achieve this, import and set up tstranslator as follows: 22 | 23 | ```py 24 | # Translate this application using Qt .ts files without the need for compilation 25 | import tstranslator 26 | tstr = tstranslator.TsTranslator(os.path.dirname(__file__) + "/i18n", "") 27 | def tr(input): 28 | return tstr.tr(input) 29 | ``` 30 | 31 | In the class that defines your MainWindow or Wizard, do the following: 32 | 33 | ```py 34 | class Wizard(QtWidgets.QWizard, object): 35 | def __init__(self): 36 | (...) 37 | # Translate the widgets in the UI objects in the Wizard 38 | self.setWindowTitle(tr(self.windowTitle())) 39 | for e in self.findChildren(QtCore.QObject, None, QtCore.Qt.FindChildrenRecursively): 40 | if hasattr(e, 'text') and hasattr(e, 'setText'): 41 | e.setText(tr(e.text())) 42 | ``` 43 | 44 | To make new strings available for translation, a developer runs in the respective application directory: 45 | 46 | ```console 47 | $ cd Resources/ 48 | $ mkdir -p i18n 49 | 50 | // Create/update .ts file for English 51 | $ pylupdate5 -noobsolete *.{py,ui} -ts i18n/en.ts 52 | 53 | // Remove unneeded location tags 54 | $ xml ed -L -d '//location' i18n/en.ts 55 | 56 | // Remove translations from en, since en is not to be further translated 57 | $ xml ed -L -d '//translation' i18n/en.ts 58 | ``` 59 | 60 | Translators do not need to do this. 61 | -------------------------------------------------------------------------------- /developer/man.md: -------------------------------------------------------------------------------- 1 | # Writing man pages 2 | 3 | Command line tools should be shipped with man pages. 4 | 5 | :::{note} 6 | To make fullest use of all features, man pages should be written in their native markup language, mdoc. 7 | 8 | However, this has a quite steep learning curve, so the following can be used to get started quickly. 9 | ::: 10 | 11 | One way to create man pages from Markdown is by using `pandoc` 12 | and the template from https://github.com/pragmaticlinuxblog/pandocmanpage. 13 | 14 | To convert Markdown to man: 15 | 16 | ```console 17 | $ pandoc Desktop/launch.1.md -s -t man -o Desktop/launch.1 18 | $ /usr/bin/man ~/Desktop/launch.1 19 | ``` 20 | 21 | To convert man to txt: 22 | 23 | ```console 24 | $ /usr/bin/man ~/Desktop/launch.1 | col -b > ~/Desktop/launch.txt 25 | ``` 26 | 27 | ## Order of sections 28 | 29 | For more information, see [`man mdoc`](https://www.freebsd.org/cgi/man.cgi?mdoc). 30 | 31 | * `PROGNAME section` 32 | * `NAME` 33 | * `LIBRARY` 34 | * `SYNOPSIS` 35 | * `DESCRIPTION` 36 | * `CONTEXT` 37 | * `IMPLEMENTATION NOTES` 38 | * `RETURN VALUES` 39 | * `ENVIRONMENT` 40 | * `FILES` 41 | * `EXIT STATUS` 42 | * `EXAMPLES` 43 | * `DIAGNOSTICS` 44 | * `ERRORS` 45 | * `SEE ALSO` 46 | * `STANDARDS` 47 | * `HISTORY` 48 | * `AUTHORS` 49 | * `CAVEATS` 50 | * `BUGS` 51 | * `SECURITY CONSIDERATIONS` 52 | -------------------------------------------------------------------------------- /developer/midi.md: -------------------------------------------------------------------------------- 1 | # MIDI 2 | 3 | Over a decade ago, someone [wrote](https://forums.freebsd.org/threads/alsa-midi-is-the-key-to-serious-musicproduction.22722/#post-158077) on the FreeBSD forum: 4 | 5 | > The main problem with anything midi and jack (in fact anything more complex than using simple audio in or audio out) under FreeBSD, is that I haven't found out how to configure things. A complete writeup (for a non-musician) about how to configure a system which use jack would be nice. 6 | 7 | This page describes how to use USB based hardware MIDI controllers (e.g., keyboards), with helloSystem and FreeBSD. 8 | 9 | :::{note} 10 | It is a work in progress. Please consider contributing additions and corrections. 11 | ::: 12 | 13 | ## Using /dev/umidi* 14 | 15 | Whenever a USB based hardware MIDI controller is plugged into the computer, a {file}`/dev/umidi*` device node is created automatically. 16 | 17 | ### Testing 18 | 19 | To test whether input from the MIDI controller arrives, run in a Terminal window: 20 | 21 | ```console 22 | $ midicat -d -q rmidi/0.0 -o /dev/null 23 | ``` 24 | 25 | As you play some notes on the MIDI controller, you should see MIDI messages appear on the screen. After verifying that this works, exit `midicat`. 26 | 27 | Some applications can use {file}`/dev/umidi*` device nodes directly. Some expect the device node to be at {file}`/dev/midi` though, so you need to create a symlink there manually. 28 | 29 | ### Example application 30 | 31 | For example, the `fluidsynth` command line tool, can use hardware MIDI controllers in this way directly: 32 | 33 | ```console 34 | $ sudo pkg install -y fluidsynth musescore 35 | $ sudo ln -sf /dev/umidi*.0 /dev/midi 36 | $ fluidsynth -m oss -a oss SoundFont.sf2 37 | ``` 38 | 39 | Unfortunately, not all applications on FreeBSD can use {file}`/dev/umidi*` device nodes directly in this way. Hence there are other methods to access MIDI controllers. which one you need to use depends on what methods the application in question supports. 40 | 41 | :::{note} 42 | Applications cannot access /dev/umidi* directly while alsa-seq-server is running. 43 | ::: 44 | 45 | ## Using OSS Raw-MIDI (Open Sound System) 46 | 47 | Supposedly applications can use "OSS Raw-MIDI (Open Sound System)" to talk to MIDI controllers. 48 | 49 | ### Testing 50 | 51 | Please let us know if you know how this works. 52 | 53 | ### Example application 54 | 55 | The LMMS FreeBSD package offers "OSS Raw-MIDI (Open Sound System)" in the dropdown menu for the MIDI interface; however, it is not clear whether and how this works on FreeBSD. Please let us know if you know how this works. 56 | 57 | ## Using alsa-seq-server 58 | 59 | Some applications can use `alsa-seq-server` to access MIDI controllers. For some applications, this support needs to be specifically enabled as a configuration option at compile time. 60 | 61 | In order for applications that use `alsa-seq-server` to talk to your MIDI controller, run 62 | 63 | ```console 64 | $ sudo pkg install alsa-seq-server alsa-utils 65 | $ sudo alsa-seq-server -d /dev/umidi* 66 | ``` 67 | 68 | and then run the application. 69 | 70 | :::{note} 71 | alsa-seq-server was recently updated so that one can run it as a service which will automatically make all MIDI devices available without having to run one instance per MIDI device. The change should appear in FreeBSD packages (and thus in helloSystem) starting in Q2/2022. 72 | ::: 73 | 74 | ### Testing 75 | 76 | To test whether input from the MIDI controller arrives, run in a separate Terminal: 77 | 78 | ```console 79 | $ aseqdump -p 0 80 | Waiting for data. Press Ctrl+C to end. 81 | Source Event Ch Data 82 | ``` 83 | 84 | As you play some notes on the MIDI controller, you should see MIDI messages appear on the screen. After verifying that this works, exit `aseqdump`. 85 | 86 | ### Example application 87 | 88 | An example application that can use `alsa-seq-server` to talk to MIDI controllers "out of the box" (without the need to recompile the application) is yet to be found in the FreeBSD Packages collection. Please let us know if you know one. 89 | 90 | Recompiling LMMS from FreeBSD Ports with the following change regarding `WANT_ALSA` in the `Makefile` allows one to use `alsa-seq-server` to talk to MIDI controllers: 91 | 92 | ```text 93 | CMAKE_OFF= WANT_CALF WANT_CAPS WANT_CMT WANT_SWH WANT_STK \ 94 | WANT_TAP WANT_VST 95 | CMAKE_ON= WANT_QT5 WANT_ALSA 96 | ``` 97 | 98 | Run `make clean ; make config ; make` to define which of the supported sound systems and MIDI interfaces will be available. LMMS can support the following MIDI interfaces on FreeBSD if it is configured accordingly at compile time: ALSA, OSS, Sndio, JACK. The ALSA one is known to work. 99 | 100 | To use it, select "ALSA-Sequencer (Advanced Linux Sound Architecture)" from the MIDI interface dropdown menu in the MIDI pane of the LMMS settings, restart ALSA, click on the gear icon e.g., in the TripleOscillator track, and select MIDI -> Input -> 0:0 (name of your USB device). 101 | 102 | If you see 103 | 104 | ```console 105 | ALSA lib seq_hw.c:466:(snd_seq_hw_open) open /dev/snd/seq failed: No such file or directory 106 | cannot open sequencer: No such file or directory 107 | ``` 108 | 109 | when you start LMMS, then most likely `sudo alsa-seq-server -d /dev/umidi*` is not running (see above). 110 | 111 | Note that depending on the application, using `alsa-seq-server` for the MIDI interface does not automatically mean that you have to use ALSA as the sound system (e.g., for the output of the generated sound). For example, if LMMS has been configured at compile time to support SDL (Simple DirectMedia Layer), you could use SDL rather than ALSA for the sound output. 112 | -------------------------------------------------------------------------------- /developer/monkey-patch.md: -------------------------------------------------------------------------------- 1 | # Monkey Patching 2 | 3 | Starting with helloSystem 0.7.0 it is possible to [monkey patch](https://en.wikipedia.org/wiki/Monkey_patch) the running 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. 4 | 5 | With that, it allows for a very rapid development-test cycle for Live ISOs. 6 | 7 | :::{note} 8 | This feature is currently under active development and its usage is still subject to change. 9 | ::: 10 | 11 | ## Theory of operation 12 | 13 | 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. 14 | 15 | If the user tells the system to perform the monkey patching, the early boot scripts in helloSystem execute code provided by the user (outside of the ISO), then continues the normal boot process. 16 | 17 | ## Creating the monkey patch volume 18 | 19 | ![image](https://user-images.githubusercontent.com/2480569/141862072-250f4d58-b5a5-4857-9bd0-70651690796e.png) 20 | 21 | * Format a USB stick with the FAT32 (`msdosfs`) file system 22 | * The volume must have the name ("filesystem label") `MONKEYPATCH` 23 | * There must be a `monkeypatch.sh` file that will be run by `#!/bin/sh` 24 | 25 | ## Booting a Live ISO applying the monkey patch on-the-fly 26 | 27 | * Boot the ISO but interrupt the bootloader by pressing the Esc key 28 | * At the boot prompt, enter: `set monkey_patch=YES` 29 | * Optionally, use `unset BOOT_MUTE` so that you can see messages on the screen during boot 30 | * Start the system by entering `boot` 31 | 32 | The code inside the file `monkeypatch.sh` on the volume called `MONKEYPATCH` will be executed before `/sbin/init` on the Live ISO is started but after most areas of the ISO have been made writable by `/boot/init_script`. 33 | 34 | ## Example `monkeypatch.sh` file 35 | 36 | ```shell 37 | #!/bin/sh 38 | 39 | # Write a file 40 | echo "HELLO MONKEY" > /tmp/MONKEY_WAS_HERE 41 | 42 | # Patch something on the ISO 43 | sed -i '' -e 's|\&\& __wait 3|\&\& sync|g' /etc/rc.d/initgfx 44 | 45 | # Show a message if the system is booted without `boot_mute` 46 | echo "HELLO DEVELOPERS" 47 | 48 | # Show a message to users in the boot process 49 | # This should be done only in rare cases since it destroys 50 | # the helloSystem zero-text boot experience 51 | echo "HELLO MERE MORTALS" > /dev/console 52 | 53 | # Give users a chance to see the message 54 | sleep 1 55 | 56 | # Override a file in the running system from the MONKEYPATCH volume 57 | HERE="$(dirname "$(readlink -f "${0}")")" 58 | cp ${HERE}/mount_md /usr/local/sbin/mount_md 59 | chmod +x /usr/local/sbin/mount_md 60 | ``` 61 | 62 | A particularly effective way to debug the late boot process (after Xorg has started) is: 63 | 64 | ```sh 65 | $ mv /usr/local/bin/start-hello /usr/local/bin/start-hello.real 66 | $ cat > /usr/local/bin/start-hello << EOF 67 | #!/bin/sh 68 | 69 | xterm -maximized start-hello.real 70 | # xterm -maximized 71 | EOF 72 | $ chmod +x /usr/local/bin/start-hello* 73 | ``` 74 | 75 | This will allow you to see the commands in `start-hello.real` as they are executed. 76 | 77 | ## Booting a Live ISO running a different `init_script` 78 | 79 | If you would like to test changes to {file}`/boot/init_script` on the ISO without having to re-create it and without having to write the ISO to a device, you can use the `monkey_patch_init_script` feature: 80 | 81 | * Boot the ISO but interrupt the bootloader by pressing the {kbd}`Esc` key 82 | * At the boot prompt, enter: `set monkey_patch_init_script=YES` 83 | * Optionally, use `unset BOOT_MUTE` so that you can see messages on the screen during boot 84 | * Start the system by entering `boot` 85 | 86 | The code inside the file `init_script` on the volume called `MONKEYPATCH` will be executed instead of {file}`/boot/init_script` on the ISO. 87 | -------------------------------------------------------------------------------- /developer/ports.md: -------------------------------------------------------------------------------- 1 | # Working with FreeBSD Ports 2 | 3 | In some situations it may be necessary to make changes to existing software that comes in FreeBSD packages. 4 | 5 | This section describes how to make such changes using an example. 6 | 7 | ## Example 8 | 9 | Suppose you would like to make a small change to the source code of software that comes as a FreeBSD package. Since packages are built from FreeBSD Ports, you need to modify the corresponding FreeBSD port. 10 | 11 | Here is a real-life example on how to do that: 12 | 13 | https://github.com/lxqt/qterminal/issues/474 can be fixed by changing a few lines in 14 | 15 | https://github.com/lxqt/qtermwidget/blob/059d832086facb19035a07d975ea4fd05d36b1ec/lib/TerminalDisplay.cpp#L3206 16 | 17 | Here is how to do it using FreeBSD Ports: 18 | 19 | ## Pulling the ports tree 20 | 21 | ```console 22 | $ sudo git clone https://git.freebsd.org/ports.git /usr/ports --depth=1 23 | ``` 24 | 25 | If you are running an end-of-life FreeBSD version such as 12.1, you also need to 26 | 27 | ```console 28 | $ export ALLOW_UNSUPPORTED_SYSTEM=1 29 | // Or in csh 30 | % setenv ALLOW_UNSUPPORTED_SYSTEM YES 31 | ``` 32 | 33 | ## Building the port without changes 34 | 35 | Build the port without changes first to ensure it builds and works as expected. 36 | 37 | ```console 38 | $ cd /usr/ports/x11-toolkits/qtermwidget/ 39 | 40 | // Install all build-time dependencies from packages 41 | $ make build-depends-list | cut -c 12- | xargs pkg install -y 42 | 43 | // Build the library 44 | // NOTE: Applications that have a library that is used by nothing but that application are just 45 | // annoying because now you have to deal with two entities rather than one 46 | $ MAKE_JOBS_UNSAFE=yes sudo -E make -j4 47 | 48 | // Now, the application itself 49 | $ cd /usr/ports/x11/qterminal 50 | 51 | // Install all build-time dependencies from packages 52 | $ make build-depends-list | cut -c 12- | xargs pkg install -y 53 | 54 | // Build the application 55 | $ QTermWidget5_DIR=/usr/ports/x11-toolkits/qtermwidget/work/stage/usr/local/lib/cmake/qtermwidget5/ MAKE_JOBS_UNSAFE=yes sudo -E make -j4 56 | 57 | // Run the application with the changed library 58 | $ LD_LIBRARY_PATH=/usr/ports/x11-toolkits/qtermwidget/work/stage/usr/local/lib/ /usr/ports/x11/qterminal/work/stage/usr/local/bin/qterminal 59 | ``` 60 | 61 | ## Making changes to the port 62 | 63 | Now make changes to the port. 64 | 65 | :::{note} 66 | In the ports system you cannot just change the source code because it would be overwritten during the build process. 67 | 68 | You first need to make a copy of the source code, then make the changes in the copy, then create a patch that will get applied automatically at build time. 69 | ::: 70 | 71 | ```console 72 | // Copy the file to be changed 73 | $ cd /usr/ports/x11-toolkits/qtermwidget 74 | $ sudo cp work/qtermwidget-*/lib/TerminalDisplay.cpp work/qtermwidget-*/lib/TerminalDisplay.cpp.orig 75 | 76 | // Make the change in the library 77 | $ sudo nano work/qtermwidget-*/lib/TerminalDisplay.cpp 78 | QChar q(QLatin1Char('\'')); 79 | dropText += q + QString(urlText).replace(q, QLatin1String("'\\''")) + q; 80 | dropText += QLatin1Char(' '); 81 | 82 | // Make a patch 83 | $ sudo make makepatch 84 | 85 | // Build the library again 86 | $ sudo make clean # Run this only if the next line does nothing 87 | $ MAKE_JOBS_UNSAFE=yes sudo -E make -j4 88 | 89 | // Run the application with the changed library 90 | $ LD_LIBRARY_PATH=/usr/ports/x11-toolkits/qtermwidget/work/stage/usr/local/lib/ /usr/ports/x11/qterminal/work/stage/usr/local/bin/qterminal 91 | ``` 92 | 93 | As a result we have a patch: 94 | 95 | ```console 96 | $ cat files/patch-lib_TerminalDisplay.cpp 97 | --- lib/TerminalDisplay.cpp.orig 2020-11-03 08:19:26 UTC 98 | +++ lib/TerminalDisplay.cpp 99 | @@ -3099,7 +3099,9 @@ void TerminalDisplay::dropEvent(QDropEvent* event) 100 | // without quoting them (this only affects paths with spaces in) 101 | //urlText = KShell::quoteArg(urlText); 102 | 103 | - dropText += urlText; 104 | + QChar q(QLatin1Char('\'')); 105 | + dropText += q + QString(urlText).replace(q, QLatin1String("'\\''")) + q; 106 | + dropText += QLatin1Char(' '); 107 | 108 | if ( i != urls.count()-1 ) 109 | dropText += QLatin1Char(' '); 110 | ``` 111 | 112 | ## Making packages 113 | 114 | Optionally, make packages for the ports. Note that `make build` needs to have run already before this step. 115 | 116 | ```console 117 | // Library 118 | $ cd /usr/ports/x11-toolkits/qtermwidget/ 119 | $ sudo make package 120 | $ ls work/pkg 121 | 122 | // Application 123 | $ cd /usr/ports/x11/qterminal 124 | $ sudo make package 125 | $ ls work/pkg 126 | ``` 127 | 128 | ## Creating a port from scratch 129 | 130 | The [FreeBSD Porter's Handbook](https://docs.freebsd.org/en/books/porters-handbook/) is the authoritative source on how to write new ports from scratch. This section shows a hands-on example on how to package a set of tools from a GitHub repository. 131 | 132 | 133 | :::{note} 134 | This section is a work in progress. Corrections are welcome. 135 | ::: 136 | 137 | First, prepare the Ports environment: 138 | 139 | ```console 140 | $ sudo su 141 | # pkg install portlint 142 | # echo DEVELOPER=yes >> /etc/make.conf 143 | ``` 144 | 145 | Next, create a directory for the new port: 146 | 147 | ```console 148 | # mkdir /usr/ports/sysutils/fluxengine 149 | # cd /usr/ports/sysutils/fluxengine 150 | ``` 151 | 152 | Create `Makefile` with the following content: 153 | 154 | ```text 155 | # $FreeBSD$ 156 | 157 | PORTNAME= fluxengine 158 | DISTVERSION= 572 159 | CATEGORIES= sysutils 160 | 161 | MAINTAINER= probono@puredarwin.org 162 | COMMENT= USB floppy disk interface for reading and writing non-PC disk formats 163 | 164 | LICENSE= MIT 165 | 166 | LIB_DEPENDS= libsqlite3.so:databases/sqlite3 \ 167 | libstdc++.so:lang/gcc9 168 | 169 | BUILD_DEPENDS= ninja:devel/ninja 170 | 171 | USES= gmake 172 | 173 | USE_GITHUB= yes 174 | GH_ACCOUNT= davidgiven 175 | GH_TAGNAME= 61ff48c 176 | 177 | do-install: 178 | ${INSTALL_PROGRAM} ${WRKSRC}/brother120tool ${STAGEDIR}${PREFIX}/bin/ 179 | ${INSTALL_PROGRAM} ${WRKSRC}/brother240tool ${STAGEDIR}${PREFIX}/bin/ 180 | ${INSTALL_PROGRAM} ${WRKSRC}/fluxengine ${STAGEDIR}${PREFIX}/bin/ 181 | 182 | .include 183 | ``` 184 | 185 | Run 186 | 187 | ```console 188 | # make makeplist > pkg-plist 189 | ``` 190 | 191 | to create that file. Check and edit it by hand, especially the first line. 192 | 193 | Notes 194 | * See `ls /usr/ports/` for possible categories, such as `sysutils` 195 | * See [5.2. Naming](https://docs.freebsd.org/en/books/porters-handbook/makefile-naming.html) for naming and versioning conventions 196 | * The lines must be in a defined order. Run `portlint` to get information on this. When `portlint` complains about `appears out-of-order`, the blocks and lines in the `Makefile` need to be reshuffled to match the order described at [https://docs.freebsd.org/en/books/porters-handbook/order/](https://docs.freebsd.org/en/books/porters-handbook/order/). 197 | * Run `make stage-qa` to find out dependencies. Using something like `make stage-qa 2>&1 | grep "you need" | sort | uniq | cut -d " " -f 4` can speed this up 198 | * The `do-install` section is needed in this example because there is no `make install` in the original software's Makefile 199 | 200 | Create `pkg-descr` based on the description on the GitHub [README.md](https://github.com/davidgiven/fluxengine): 201 | 202 | ```text 203 | The FluxEngine is a very cheap USB floppy disk interface capable of 204 | reading and writing exotic non-PC floppy disk formats. 205 | It allows you to use a conventional PC drive to accept Amiga disks, 206 | CLV Macintosh disks, bizarre 128-sector CP/M disks, 207 | and other weird and bizarre formats. 208 | : 209 | The hardware consists of a single, commodity part with a floppy drive 210 | connector soldered onto it. No ordering custom boards, 211 | no fiddly surface mount assembly, and no fuss: 212 | nineteen simpler solder joints and you're done. 213 | 214 | WWW: http://cowlark.com/fluxengine/ 215 | ``` 216 | 217 | Notes 218 | * For details please refer to [3.2. Writing the Description Files](https://docs.freebsd.org/en/books/porters-handbook/porting-desc.html). 219 | 220 | Create the checksum file by running 221 | 222 | ```console 223 | # make makesum 224 | ``` 225 | 226 | Check the Makefile with 227 | 228 | ```console 229 | # portlint 230 | ``` 231 | 232 | and correct any mistakes it reports, then repeat. 233 | 234 | Once `portlint` says `looks fine`, try to build by running 235 | 236 | ```console 237 | # make 238 | ``` 239 | 240 | Note that the compilation will fail. This is because in this case the application needs to be built with `gmake` rather than `make`. 241 | 242 | Run tests 243 | 244 | ```console 245 | # make stage 246 | # make stage-qa 247 | # make package 248 | # make install 249 | # make deinstall 250 | ``` 251 | 252 | None of these must produce errors. See [3.4. Testing the Port](https://docs.freebsd.org/en/books/porters-handbook/porting-testing.html) for details. 253 | 254 | At this point it may be a good idea to have an experienced FreeBSD Ports developer have a look at your new port. 255 | 256 | Once everything looks good, prepare a `.shar` file for submitting it to https://bugs.freebsd.org/submit/: 257 | 258 | ```console 259 | # rm -rf work/ 260 | # cd .. 261 | # tar cf fluxengine.shar --format shar fluxengine 262 | ``` 263 | 264 | ## Updating existing ports 265 | 266 | This real-life example shows how to update a port, e.g., `x11/qterminal`. 267 | 268 | ```console 269 | $ sudo su 270 | # cd /usr/ports 271 | # git pull 272 | # cd x11/qterminal 273 | ``` 274 | 275 | Change `PORTVERSION= 1.1.0` to `PORTVERSION= 1.2.0`. Turns out that one has to update `x11-toolkits/qtermwidget` and `devel/lxqt-build-tools` too for it to compile. 276 | 277 | ```console 278 | # portlint # Fix errors, if any 279 | # rm pkg-plist 280 | # make clean 281 | # make package reinstall 282 | # make makeplist > pkg-plist 283 | # nano pkg-plist # Remove first line and check the others 284 | # make clean 285 | # make package reinstall 286 | ``` 287 | 288 | Finally, once everything is tested, create separate patches for each port with 289 | 290 | ```console 291 | # cd /usr/ports 292 | # git diff -U999999 x11/qterminal > /home/user/Desktop/x11_qterminal.diff 293 | # git diff -U999999 devel/lxqt-build-tools > /home/user/Desktop/devel_lxqt-build-tools.diff 294 | # git diff -U999999 x11-toolkits/qtermwidget > /home/user/Desktop/x11-toolkits_qtermwidget.diff 295 | ``` 296 | 297 | Go to https://reviews.freebsd.org/differential/, click "Create Diff", can log in using GitHub credentials, subject `devel/lxqt-build-tools: Update to 0.12.0`, under "Reviewers" add the maintainer. 298 | 299 | Result: 300 | * https://reviews.freebsd.org/D37378 301 | * https://reviews.freebsd.org/D37379 302 | * https://reviews.freebsd.org/D37380 303 | 304 | If a reviewer requires changes to be made, make the changes and upload (paste) a new diff (like the original diff; not a "diff of the diff"!) by clicking on "Update Diff" on the respective Phabricator page, e.g., https://reviews.freebsd.org/D37378. 305 | -------------------------------------------------------------------------------- /developer/rpi.md: -------------------------------------------------------------------------------- 1 | # Raspberry Pi 2 | 3 | ![](https://camo.githubusercontent.com/9e96cf15fbd387092abc4fd6ede84e29cee79892d4d912d0a44b63ca7fe8cb5e/68747470733a2f2f7062732e7477696d672e636f6d2f6d656469612f457a48427433575845414d7131556e3f666f726d61743d6a7067266e616d653d736d616c6c) 4 | 5 | Although we are currently not providing installation images for Raspberry Pi, we are investigating whether doing so would be feasible and beneficial. 6 | 7 | The same instructions are roughly applicable to other aarch64 based systems such as rk3399 ones like the PineBook Pro and the [pine64 rockpro64_rk3399](https://bsd-hardware.info/?id=board:pine64-pinebook-pro-rk3399) as well. 8 | 9 | :::{note} 10 | This page is intended for technically advanced users and developers, not for end users. This page is work in progress. Instructions are brief and assume prior knowledge with the subject. 11 | ::: 12 | 13 | This page describes how to run the main components of helloSystem (referred to collectively as helloDesktop) on Raspberry Pi 3 and Raspberry Pi 4 devices, starting with the official FreeBSD 13 image that does not even contain Xorg. 14 | 15 | It describes how to build and set up the main components of helloSystem by hand, so this is a good walkthrough in case you are interested in bringing up the helloDesktop on other systems as well. 16 | 17 | If there is enough interest, we might eventually provide readymade helloSystem images for Raspberry Pi in the future. This depends on how usable helloSystem will be on the Raspberry Pi (e.g., whether we can get decent graphics performance). 18 | 19 | ## Prerequisites 20 | 21 | * Raspberry Pi 3 Model B or B+, Raspberry Pi 4 Model B, or Raspberry Pi 400 22 | * Suitable power supply 23 | * Class-1 or faster microSD card with at least 8 GB of memory 24 | * HDMI display 25 | * Keyboard and mouse (we recommend the official Raspberry Pi keyboard since helloSystem can automatically detect its language) 26 | * Ethernet (WLAN is not yet covered on this page) 27 | 28 | ## Optional hardware 29 | 30 | * SATA SSD drive (not NVME) 31 | 32 | ## Preparing an SD card 33 | 34 | * Install the official FreeBSD 13 image (not FreeBSD 14) to a microSD card 35 | * Copy this file to the microSD card you are running the Raspberry Pi from. You will need it because you will not have an internet browser at hand 36 | * Edit `config.txt` in the `MSDOSBOOT` partition to contain the correct resolution for your screen. 37 | 38 | ```text 39 | hdmi_safe=0 40 | disable_overscan=1 41 | display_auto_detect=1 42 | max_framebuffer_width=3840 43 | max_framebuffer_height=2160 44 | max_framebuffers=2 45 | gpu_mem=512 46 | 47 | [pi4] 48 | dtoverlay=vc4-kms-v3d-pi4 49 | ``` 50 | 51 | :::{note} 52 | If, for some reason, the display does not work, simply remove or comment out the `max_framebuffer*` lines and replace them with the following: 53 | 54 | ```text 55 | framebuffer_width= 56 | framebuffer_height= 57 | ``` 58 | ::: 59 | 60 | ## Preparing a bootable SSD drive (optional but recommended) 61 | 62 | * [Update your firmware if USB boot is not working](https://www.raspberrystreet.com/learn/how-to-boot-raspberrypi-from-usb-ssd) 63 | * Follow the instructions in the SD card section, but write the image to your SSD 64 | 65 | :::{note} 66 | The Raspberry Pi 4/400 doesn't have a PCIe bus, so booting off an NVMe drive over USB protocol is not supported by the hardware. You will need to use a SATA SSD. This works for either M.2 or traditional drive form factors. 67 | ::: 68 | 69 | ## Booting into the system 70 | 71 | We will be doing all subsequent steps on the Raspberry Pi system itself since we are assuming you don't have any other 64-bit ARM (`aarch64`) machines at hand. 72 | 73 | * Insert the microSD card into the Raspberry Pi 74 | * Attach keyboard and mouse (we recommend the official Raspberry Pi keyboard since helloSystem can automatically detect its language) 75 | * Attach the display (If you don't see anything, DO NOT power off your machine. Simply switch the HDMI port.) 76 | * Attach Ethernet 77 | * Power on the Raspberry Pi 78 | * After some time, you should land in a login screen 79 | * Log in with `root`, password `root` 80 | * Install some basic software with `pkg install -y xorg xterm nano openbox fluxbox git-lite` 81 | 82 | :::{note} 83 | `fluxbox` is not strictly needed and can be removed later on, but it gives us a graphical desktop session while we are working on installing helloDesktop 84 | ::: 85 | 86 | ## Starting a graphical session 87 | 88 | Start Xorg with 89 | 90 | ```console 91 | # echo startfluxbox > ~/.xinitrc 92 | # startx 93 | ``` 94 | 95 | Doing it like this is the easiest way since the display `DISPLAY` environment variable and other things will be set automatically. 96 | 97 | ## Compiling and installing helloDesktop core components 98 | 99 | ### Install prerequisites 100 | 101 | ```console 102 | # pkg install -y cmake pkgconf qt5-qmake qt5-buildtools kf5-kdbusaddons kf5-kwindowsystem libdbusmenu-qt5 qt5-concurrent qt5-quickcontrols2 libfm libqtxdg wget 103 | ``` 104 | 105 | ### launch 106 | 107 | The `launch` command is central to helloSystem and is used to launch applications throughout the system. 108 | 109 | ```console 110 | # git clone https://github.com/helloSystem/launch 111 | # cd launch/ 112 | # mkdir build 113 | # cd build/ 114 | # cmake .. 115 | # make -j4 116 | # ./launch 117 | # make install 118 | # cd ../../ 119 | ``` 120 | 121 | ### Menu 122 | 123 | ```console 124 | # git clone https://github.com/helloSystem/Menu 125 | # cd Menu 126 | # mkdir build 127 | # cd build 128 | # cmake .. 129 | # make -j4 130 | # make install 131 | # ln -s /usr/local/bin/menubar /usr/local/bin/Menu # Workaround for the 'launch' command to find it 132 | # cd ../../ 133 | ``` 134 | 135 | ### Filer 136 | 137 | ```console 138 | # git clone https://github.com/helloSystem/Filer 139 | # cd Filer/ 140 | # mkdir build 141 | # cd build/ 142 | # cmake .. 143 | # make -j4 144 | # make install 145 | # ln -s /usr/local/bin/filer-qt /usr/local/bin/Filer # Workaround for the 'launch' command to find it 146 | # cd ../../ 147 | ``` 148 | 149 | :::{note} 150 | It seems like Filer refuses to start if D-Bus is missing. We should change it so that it can also work without D-Bus and at prints a clear warning if D-Bus is missing. Currently all you see if D-Bus is missing is the following: '** (process:3691): WARNING **: The directory '~/Templates' doesn't exist, ignoring it', and then Filer exits. 151 | ::: 152 | 153 | ### Dock 154 | 155 | ```console 156 | # pkg install -y <...> 157 | # git clone https://github.com/helloSystem/Dock 158 | # cd Dock 159 | # mkdir build 160 | # cd build 161 | # cmake .. 162 | # make -j4 163 | # make install 164 | // Currently Dock is installed to /usr/bin/cyber-dock. In the future is should be in /usr/local/bin/. 165 | # ln -s /usr/bin/cyber-dock /usr/local/bin/Dock # Workaround for the 'launch' command to find it 166 | # cd ../../ 167 | ``` 168 | 169 | ### QtPlugin 170 | 171 | ```console 172 | # git clone https://github.com/helloSystem/QtPlugin 173 | # cd QtPlugin/ 174 | # mkdir build 175 | # cd build/ 176 | # cmake .. 177 | # make -j4 178 | # make install 179 | # cp ../stylesheet.qss /usr/local/etc/xdg/ 180 | # cd ../../ 181 | ``` 182 | 183 | ### Icons and other assets 184 | 185 | Install icons and other helloSystem assets that are not packaged as FreeBSD packages (yet). It is easiest to run `bash`, then `export uzip=/`, and then run the corresponding sections of [script.hello](https://raw.githubusercontent.com/helloSystem/ISO/experimental/settings/script.hello). Here are some examples. 186 | 187 | For the system icons: 188 | 189 | ```console 190 | # wget -c -q http://archive.ubuntu.com/ubuntu/pool/universe/x/xubuntu-artwork/xubuntu-icon-theme_16.04.2_all.deb 191 | # tar xf xubuntu-icon-theme_16.04.2_all.deb 192 | # tar xf data.tar.xz 193 | # mkdir -p "${uzip}"/usr/local/share/icons/ 194 | # mv ./usr/share/icons/elementary-xfce "${uzip}"/usr/local/share/icons/ 195 | # mv ./usr/share/doc/xubuntu-icon-theme/copyright "${uzip}"/usr/local/share/icons/ elementary-xfce/ 196 | # sed -i -e 's|usr/share|usr/local/share|g' "${uzip}"/usr/local/share/icons/elementary-xfce/copyright 197 | # rm "${uzip}"/usr/local/share/icons/elementary-xfce/copyright-e 198 | # wget "https://raw.githubusercontent.com/helloSystem/hello/master/branding/computer-hello.png" -O "${uzip}"/usr/local/share/icons/elementary-xfce/devices/128/computer-hello.png 199 | ``` 200 | 201 | For the system fonts: 202 | 203 | ```console 204 | # wget -c -q https://github.com/ArtifexSoftware/urw-base35-fonts/archive/20200910.zip 205 | # unzip -q 20200910.zip 206 | # mkdir -p "${uzip}/usr/local/share/fonts/TTF/" 207 | # cp -R urw-base35-fonts-20200910/fonts/*.ttf "${uzip}/usr/local/share/fonts/TTF/" 208 | # rm -rf urw-base35-fonts-20200910/ 20200910.zip 209 | ``` 210 | 211 | Proceed similarly for the cursor theme, wallpaper, applications from the helloSystem/Utilities repository, and other assets. 212 | 213 | ### Installing required packages 214 | 215 | Install every package that is not commented out in [packages.hello](https://raw.githubusercontent.com/helloSystem/ISO/experimental/settings/packages.hello) that are installable. 216 | 217 | :::{note} 218 | Not every package will be installable. This probably means that the package in question has not been compiled for the `aarch64` architecture on FreeBSD 13 yet. 219 | ::: 220 | 221 | You can use this script to automatically install all listed packages: 222 | 223 | ```sh 224 | #!/bin/sh 225 | 226 | url="https://raw.githubusercontent.com/helloSystem/ISO/experimental/settings/packages.hello" 227 | curl -fsS $url | egrep -v '^#' | while read line ; do 228 | pkg install -y -U $line || echo "[error] $line cannot be installed" 229 | done 230 | ``` 231 | 232 | To enable `automount`, run `service devd restart`. 233 | 234 | ### Installing overlays 235 | 236 | ```console 237 | # git clone https://github.com/helloSystem/ISO 238 | # cp -Rfv ISO/overlays/uzip/hello/files/ / 239 | # cp -Rfv ISO/overlays/uzip/localize/files/ / 240 | # cp -Rfv ISO/overlays/uzip/openbox-theme/files/ / 241 | # cp -Rfv ISO/overlays/uzip/mountarchive/files/ / 242 | ``` 243 | 244 | :::{note} 245 | If we provided the temporary packages that are used in the helloSystem ISO build process for download, then one could just install those instead of having to do the above. 246 | ::: 247 | 248 | ## Adjusting fstab 249 | 250 | Edit {file}`/etc/fstab` to look like this: 251 | 252 | ```text 253 | /dev/mmcsd0s2a / ufs rw 0 0 254 | ``` 255 | 256 | Otherwise the root device may not be found upon reboot. 257 | 258 | ### Enabling D-Bus and Avahi 259 | 260 | Filer does not launch and Zeroconf does not work if `/usr/local/bin/dbus-daemon --system` is not running. Hence add the following lines to `/etc/rc.conf' to enable it: 261 | 262 | ```text 263 | dbus_enable="YES" 264 | avahi_enable="YES" 265 | ``` 266 | 267 | and then start it `service dbus start`. 268 | 269 | ### Editing start-hello 270 | 271 | Edit the `start-hello` script to use the `launch` command instead of hardcoding `/Applications/...`. 272 | 273 | ```text 274 | ################################# 275 | # Details to be inserted here. 276 | # This script is work in progress. 277 | ################################# 278 | ``` 279 | 280 | ### Starting helloDesktop session 281 | 282 | ```console 283 | # echo start-hello > ~/.xinitrc 284 | # killall Xorg 285 | ``` 286 | 287 | Type `startx` to start an Xorg session; it should now load a helloDesktop session. 288 | 289 | Sometimes it does not load all the way, in this case it is necessary to start xterm (right-click the desktop) and invoke `start-hello` from there again. The reason for this is unknown. 290 | 291 | ### Adding a user 292 | 293 | Added a new user with Applications -> Preferences -> Users 294 | 295 | ```console 296 | # cp /home/user/.openbox* . 297 | # cp -r /home/user/.config/* .config/ 298 | ``` 299 | 300 | ## Improving system performance 301 | 302 | ### Setting up SWAP for greater system memory capabilities 303 | 304 | :::{note} 305 | While this will work on an SD card, it will be slow and wear out your drive quickly. Take it from me, SD cards SUCK for quick memory page access. It is highly recommended to use a SATA SSD when using SWAP. This section was adapted from [a guide on nixCraft](https://www.cyberciti.biz/faq/create-a-freebsd-swap-file/). It goes into more detail and even breifly covers encryption. 306 | ::: 307 | 308 | * Create a SWAP file using 309 | 310 | ```console 311 | # dd if=/dev/zero of=/swap bs=1M count=8192 312 | ``` 313 | 314 | :::{note} 315 | This will create a swap file holding up to 8192 MB (8 GB) of memory. To go much further beyond that would recommend some further tweaking. 8 GB should be more than enough. It's easy enough to convert what you want in GB to MB, but for the sake of convenience, multiply how much memory you want in gigabytes (GB) by 1024. For example, if you wanted 4 GB, you'd do 4*1024=4096. 316 | ::: 317 | 318 | * Run `# chmod 0600 /swap` to give it the correct permissions. 319 | * Edit /etc/fstab and append the following line: 320 | 321 | ```text 322 | md42 none swap sw,file=/swap 0 0 323 | ``` 324 | 325 | * Run `# swapon -aq` to immediately enable SWAP 326 | * Run `$ swapinfo -k` to verify that it's been attached correctly 327 | 328 | ### Overclocking your system 329 | 330 | With an SSD, SWAP, and several GPU enhancements enabled, you should immediately notice a speed boost. This will give you a much better development system and may even replace your desktop. However, you can quickly and easily take it a step further by overclocking your system. Please note, overclocking can lead to reduced hardware lifespan and can cause permenant damage. That said, I've found that a decent heat sing and a good fan go the trick. This is necessary as not having a somewhat competatant cooling solution will bite you in the ass. If you let it heat too much, it will thermal throttle and kill your performance. Do keep in mind, you need a good power supply to run this thing, especially overclocked. A Raspberry Pi power supply is a little different than a normal phone charger by design. Your new iPhone or MacBook charger probably won't cut it. I'd recommend getting the [official Rasbperry Pi power supply](https://www.amazon.com/Raspberry-Power-Supply-USB-C-Listed/dp/B07Z8P61DQ), manufactured by the Rasbperry Pi Foundation or whatever. Ir's OEM, it's good. Another great option is the [Argon ONE](https://www.amazon.com/Argon-Raspberry-Supply-Listed-Adapter/dp/B07TW4Q693) power supply. 331 | 332 | Overclocking is inherently dangerous as you are pushing the device beyond the intended spec. However, it is a very simple and robust machine that will most likely experience no ussues doing this. The Raspberry Pi is very affordable and modular, making the risk of hardware failure less of an issue. The main board can easily be swapped out and EEPROM flashed and you have your whole system back. There's a hard limit to how far you can push your Pi, so don't even worry about overdoing it. No 8 GHz liquid nitrogen overclocks I'm afraid. 333 | 334 | To overclock you Raspberry Pi 4 to the max, edit {file}`/boot/msdos/config.txt` and append the following: 335 | 336 | ```text 337 | over_voltage=6 338 | arm_freq=2147 339 | gpu_freq=700 340 | ``` 341 | 342 | 2147 MHz is the maximum the device can go. Unlike Raspberry Pi OS, FreeBSD will boot even if you set these values higher. Even though you can set it higher, I can see no difference, even at 3000. You can set the gpu_freq up to "900" before it refuses to boot on FreeBSD. However, I can't tell if it is actually working or not. Even if you can push it past its limits, you will probaby see diminishing returns. In the event that you actually can overclock it to these badass levels, I'd recommend investing in a monster CPU cooler, maybe even running liquid cooling or higher as 2147 MHz is already pretty warm. 343 | 344 | ## Known issues 345 | 346 | :::{note} 347 | Any help in improving the situation is appreciated. 348 | ::: 349 | 350 | Not sure whether `vc4-kms-v3d` is usable with FreeBSD. 351 | 352 | Also see: https://papers.freebsd.org/2019/bsdcan/vadot-adventure_in_drmland/ 353 | 354 | ### Missing login window 355 | 356 | The `slim` package is missing, hence we don't have a login window at the moment. 357 | 358 | :::{note} 359 | Web browser performance may be improved and the following issues may not be relevant anymore. This will require more user feedback and testing. 360 | ::: 361 | 362 | ### Web browser 363 | 364 | The Falkon browser can be launched, but trying to load more than the most basic web pages such as http://frogfind.com/ leads to an instant crash: 365 | 366 | ```console 367 | # cat /root/.config/falkon/crashlog/Crash-2021-04-17T10:21:20.txt 368 | Time: Sa. Apr. 17 10:21:20 2021 369 | Qt version: 5.15.2 (compiled with 5.15.2) 370 | Falkon version: 3.1.0 371 | Rendering engine: QtWebEngine 372 | 373 | ============== BACKTRACE ============== 374 | #0: 0x213810 at /usr/local/bin/falkon 375 | #1: 0x499b4994 <_pthread_sigmask+0x524> at /lib/libthr.so.3 376 | ``` 377 | 378 | :::{note} 379 | The exact same crash also happens on a RockPro64 with 4GB of RAM. 380 | ::: 381 | 382 | ### RAM compression 383 | 384 | On Linux, there is also __zram__ which is enabled by default on Android and Chromium OS. Did anything ever come out of https://wiki.freebsd.org/SummerOfCode2019Projects/VirtualMemoryCompression? 385 | 386 | macOS also does RAM compression when memory is getting low: https://www.lifewire.com/understanding-compressed-memory-os-x-2260327. 387 | 388 | Windows also does RAM compression: https://www.tenforums.com/windows-10-news/17993-windows-10-memory-compression.html. 389 | 390 | The following seems to "work" but can make the Raspberry Pi unacceptably slow: 391 | 392 | ```console 393 | # mdconfig -a -t malloc -o compress -o reserve -s 700m -u 7 394 | # swapon /dev/md7 395 | ``` 396 | 397 | :::{note} 398 | Please let us know if you know how to properly use RAM compression on FreeBSD. 399 | ::: 400 | 401 | :::{note} 402 | Do not use ZFS on memory-constrained machines. 403 | ::: 404 | 405 | ### Missing icons 406 | 407 | Set `QT_QPA_PLATFORMTHEME` env variable before staring Xorg session. 408 | 409 | ```console 410 | setenv QT_QPA_PLATFORMTHEME panda 411 | ``` 412 | -------------------------------------------------------------------------------- /developer/specifications.md: -------------------------------------------------------------------------------- 1 | # Specifications 2 | 3 | helloSystem is designed to be friendly and welcoming. The desired user experience informs the specifications embraced for use in helloSystem and applications running on it. 4 | 5 | ## Specifications embraced for use in helloSystem 6 | 7 | These specifications cover technologies that are enthusiastically embraced in helloSystem and/or are recommended to be used in applications running on it. 8 | 9 | * __mDNS__: Allows hostnames of devices to be published to the network, so that devices can be accessed using their names rather than using IP numbers. 10 | * __DNS-SD/Zeroconf__: Allows for the discovery of services on the network, such as websites, SSH servers, SFTP shares, etc. If an application can handle certain types of network services, it should discover such services using DNS-SD/Zeroconf. For example, a Terminal application might offer to connect to SSH servers on the network discovered with DNS-SD/Zeroconf. 11 | * __IPP Everywhere__: Allows printers to "just work" without configuring printer drivers. 12 | * __AppImage__: Allows applications to be shipped and used as single files. helloSystem may predominantly use this format for Linux applications in the future. 13 | * __Markdown__: The standard format for all documentation and other written text. 14 | * __UTF-8__: The default encoding for text. 15 | 16 | This list is not exhaustive. 17 | 18 | ## Conventions developed for use in helloSystem 19 | 20 | These conventions cover technologies that are embraced for being used in helloSystem and applications running on it. 21 | 22 | * __Simplified application bundles:__ The format helloSystem predominantly uses for native applications. Derived from the GNUstep `.app` bundle format, but further simplified. Not formally specified yet. 23 | 24 | This list is not exhaustive. 25 | 26 | ## Specifications with relevance for helloSystem 27 | 28 | These specifications cover technologies that may have relevance for helloSystem and are mostly considered for compatibility reasons. Their use within helloSystem may decline over time as more native replacements become available. 29 | 30 | * __ICCCM/EWMH__: Allows windows to be managed on Xorg. [This page in the picom wiki](https://github.com/yshui/picom/wiki/Window-states-management) gives an overview 31 | * __D-Bus__: Allows processes on the system to interact with each other (inter-process communication, IPC) 32 | * __XDG Desktop specification__: Although helloSystem uses simplified application bundles to provide the desired user experience, some existing applications in FreeBSD ports and packages may come with `.desktop` files. To maintain compatibility with the vast body of existing applications, helloSystem needs to provide a basic implementation of this specification, although its use should be minimized in helloSystem to allow for the desired user experience. For example, all handling of `.desktop` files could be left to one command line tool such as `desktop2app` that would convert `.desktop` files into the format used natively in helloSystem. Other uses of the XDG Desktop specification may be phased out in the future 33 | 34 | This list is not exhaustive. 35 | -------------------------------------------------------------------------------- /developer/tracing.md: -------------------------------------------------------------------------------- 1 | # Tracing with DTrace/dtruss 2 | 3 | The `dtruss` command line tool can be used to examine what a running process is doing. Other than, e.g., `strace` on Linux, `dtruss` can be used to watch already-running processes. This makes it more suitable to watch processes that have been launched by, e.g., the `launch` command. 4 | 5 | ```console 6 | $ sudo pkg install dtrace-toolkit 7 | $ sudo kldload dtraceall 8 | $ launch FeatherPad 9 | // In another terminal: 10 | $ ps ax | grep featherpad 11 | // Then use the PID of the featherpad process for the next command: 12 | $ sudo dtruss -p 1886 -f 13 | ``` 14 | 15 | 16 | :::{note} 17 | If you get `probe description syscall:::entry does not match any probes`, then possibly you loaded `kldload dtrace` rather than `kldload dtraceall`. 18 | ::: 19 | 20 | The [FreeBSD DTrace Tutorial](https://wiki.freebsd.org/DTrace/Tutorial) has many one-liner examples for tasks like observing 21 | 22 | * File Opens 23 | * Syscall Counts By Process 24 | * Distribution of read() Bytes 25 | * Timing read() Syscall 26 | * Measuring CPU Time in read() 27 | * Count Process-Level Events 28 | * Profile On-CPU Kernel Stacks 29 | * Scheduler Tracing 30 | * TCP Inbound Connections 31 | * Raw Kernel Tracing 32 | 33 | There is also a full list of [DTrace One-Liners](https://wiki.freebsd.org/DTrace/One-Liners) to pick up more DTrace functionality. 34 | 35 | :::{note} 36 | In the future a graphical utility might be written to automate common tracing tasks. 37 | ::: 38 | -------------------------------------------------------------------------------- /developer/ux-guidelines.md: -------------------------------------------------------------------------------- 1 | # User Experience Guidelines 2 | 3 | Since helloSystem is intended to be friendly and welcoming to switchers from the Mac, it is important to understand the underlying concepts and design considerations that went into the Mac. We are not aiming to create a 1:1 replica, but something that is generally consistent with the underlying general user experience (UX) philosophy, which has been openly documented. 4 | 5 | ## Macintosh Human Interface Guidelines 6 | 7 | What are the design principles that make user interfaces "Mac-like"? Apple spelled them out for us publicly 30 years ago in a book, the Macintosh Human Interface Guidelines. Besides describing what makes user interfaces "Mac-like", the book also explains general concepts like how to perform user testing. 8 | 9 | > If you are a designer, a human interface professional, or an engineer, this book contains information you can use to design and create products that fit the Macintosh model. It provides background information that can help you plan and make decisions about your product design. __Even if you don’t design and develop products for the Macintosh, reading this book will help you to understand the Macintosh interface.__ 10 | 11 | Source: [Apple Computer, Inc., 1992, Macintosh Human Interface Guidelines, First Printing, November 1992. Addison-Wesley Publishing Company. ISBN 0-201-62216-5](https://dl.acm.org/doi/book/10.5555/573097) 12 | 13 | ## Using the global menu bar 14 | 15 | ### Walker, N & Smelcer, 1990 (Superiority of the global menu bar) 16 | 17 | Referred to in the Macintosh Human Interface Guidelines with highest praise: 18 | 19 | > A seminal paper on why pull-down menus are superior to any other kind. 20 | > Everyone who designs for the screen must read this paper. 21 | 22 | This paper provides empirical evidence on the superiority of global menus. 23 | 24 | > Systems that maximize the percentage of menu items with borders will have a decided 25 | advantage over other menu systems. 26 | > 27 | > In this experiment the initial movement to the pull-down menus was larger that 28 | average distance required to reach the top of a 19 inch diagonal screen, yet the pull-downs still significantly outperformed the walking menus. Therefore, it may be 29 | more efficient to place menus at the top of the window 30 | 31 | Source: Walker, N & Smelcer, JB 1990, A comparison of selection times from walking and pull-down menus. in JC Chew & J Whiteside (eds), Proceedings of the SIGCHI Conference on Human Factors in Computing Systems, CHI 1990. Association for Computing Machinery, pp. 221-225, 1990 SIGCHI Conference on Human Factors in Computing Systems, CHI 1990, Seattle, United States, 4/1/90. 32 | 33 | ## Avoiding hidden menus hamburger icons 34 | 35 | Menus hidden behind hamburger menus have been [proven to hurt user experience]( https://www.nngroup.com/articles/hamburger-menus/). They should not be used. The global menu bar should be used instead. 36 | 37 | ## Avoiding configuration options 38 | 39 | Configuration options add complexity to software, increase the test matrix, and make software harder to support (e.g., over the phone) because no two systems behave exactly the same way depending on how they were configured. Hence in helloSystem we want to avoid unnecessary user-facing configuration options whenever possible. We take great care to set sensible defaults and make things "just work" as expected (in line with our design objectives) out of the box, without the need for configuration. KDE Plasma is recommended as an alternative for users who wish to configure and customize every aspect of the system. 40 | -------------------------------------------------------------------------------- /index.md: -------------------------------------------------------------------------------- 1 | ```{image} https://raw.githubusercontent.com/helloSystem/hello/1d1e69be8a689c5e0a176df821c14f0b49b241a4/branding/hello_variation.svg 2 | :alt: The helloSystem logo 3 | :width: 300px 4 | :align: center 5 | ``` 6 | 7 | ```{eval-rst} 8 | .. centered:: Willkommen • Welcome • Bienvenue • Benvenuto • Bienvenido • ようこそ • Mabuhay • Tervetuloa • Välkommen • Добро пожаловать • Hoş geldiniz • Bonvenon • 歡迎 • Ласкаво просимо • 欢迎 9 | ``` 10 | 11 | # hello 12 | 13 | __helloSystem__ is a desktop system for creators with a focus on simplicity, elegance, and usability. Its design follows the "Less, but better" philosophy. It is intended as a system for "mere mortals", welcoming to switchers from the Mac. [FreeBSD](https://www.freebsd.org/) is used as the core operating system. Please refer to [https://github.com/helloSystem/hello](https://github.com/helloSystem/hello) if you would like to learn more about the ideas and principles behind hello. 14 | 15 | ![Screenshot](https://github.com/helloSystem/hello/blob/master/screenshots/20220121-desktop-0.8.png?raw=true) 16 | 17 | ```{toctree} 18 | --- 19 | maxdepth: 3 20 | caption: User Guide 21 | hidden: true 22 | glob: true 23 | --- 24 | 25 | user/getting-started 26 | user/components 27 | user/troubleshooting 28 | user/feedback 29 | ``` 30 | 31 | ```{toctree} 32 | --- 33 | caption: Reviewer Guide 34 | hidden: true 35 | maxdepth: 2 36 | glob: true 37 | --- 38 | 39 | reviewer/guide 40 | ``` 41 | 42 | ```{toctree} 43 | --- 44 | caption: Developer Guide 45 | hidden: true 46 | maxdepth: 2 47 | glob: true 48 | --- 49 | 50 | developer/ux-guidelines 51 | developer/architecture 52 | developer/boot 53 | developer/geom_rowr 54 | developer/graphics 55 | developer/binary-compatibility 56 | developer/applications 57 | developer/application-bundles 58 | developer/menu 59 | developer/filer-context-menus 60 | developer/developer-tools 61 | developer/midi 62 | developer/specifications 63 | developer/contributing 64 | developer/building 65 | developer/monkey-patch 66 | developer/tracing 67 | developer/localization 68 | developer/ports 69 | developer/base 70 | developer/man 71 | developer/rpi 72 | developer/linux 73 | developer/distributions 74 | developer/acknowledgements 75 | developer/contact 76 | 77 | ``` 78 | -------------------------------------------------------------------------------- /make.sh: -------------------------------------------------------------------------------- 1 | #! /bin/bash 2 | 3 | set -e 4 | 5 | CUR_DIR=$(readlink -f $(dirname "$0")) 6 | 7 | cd "$CUR_DIR" 8 | 9 | VENV="$CUR_DIR"/.venv 10 | 11 | if [ ! -d "$VENV" ] || [ ! -e "$VENV"/bin/activate ]; then 12 | echo $(tput bold)$(tput setaf 2)"Creating new virtual environment in $VENV"$(tput sgr0) 13 | PYTHON=python3 14 | which python3.6 &>/dev/null && PYTHON=python3.6 15 | "$PYTHON" -m venv "$VENV" 16 | fi 17 | 18 | source "$VENV"/bin/activate 19 | 20 | # this snippet should allow us to call pip install only if the requirements file has been touched 21 | if [ ! -f "$VENV"/requirements.txt ] || [ $(sha256sum requirements.txt | cut -d' ' -f1) != $(sha256sum "$VENV"/requirements.txt | cut -d' ' -f1) ]; then 22 | echo $(tput bold)$(tput setaf 2)"Requirements updated, reinstalling"$(tput sgr0) 23 | cp requirements.txt "$VENV"/requirements.txt 24 | pip install -U -r "$VENV"/requirements.txt 25 | fi 26 | 27 | make "$@" 28 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | wheel 2 | sphinx>=5.0.0 3 | sphinx_rtd_theme>=0.5.2 4 | sphinx-autobuild 5 | sphinx-last-updated-by-git 6 | myst-parser 7 | sphinxcontrib-qthelp 8 | # docutils needs to be pinned for now so that lists work 9 | # See https://github.com/readthedocs/sphinx_rtd_theme/issues/1115 for more information 10 | docutils==0.16 11 | -------------------------------------------------------------------------------- /reviewer/guide.md: -------------------------------------------------------------------------------- 1 | # Reviewer Guide 2 | 3 | ## Introduction 4 | 5 | helloSystem is an open-source operating system that builds on FreeBSD as a rock solid foundation. Its goal is to provide a friendly, highly usable, and visually appealing system for desktop and notebook computers. The system is designed to be easy to use, efficient, with an emphasis on minimalism and simplicity. 6 | 7 | Its target audience are switchers from the Mac platform, to which it aims to provide an environment in which they can feel instantly at home. 8 | 9 | The purpose of this guide is to provide an overview of helloSystem, as well as to offer guidance on how to use the system's features and capabilities. The guide includes information on system requirements, installation, user interface, features, performance, support options, and more. When reviewing helloSystem, try to look at it from a perspective of long-time Mac users, particularly those who are doing creative work like graphics, design, video editing, or 3D modeling and printing but who would like to do so using open source applications. This guide should provide you with a thorough understanding of the system and its functionality and should give you a starting point for your own exploration. 10 | 11 | ## System Requirements 12 | 13 | To run helloSystem, you will need a system that meets the following minimum requirements: 14 | 15 | - 64-bit x86 processor 16 | - 2 GB of RAM 17 | - Dedicated storage device with at least 10 GB of available space 18 | - Graphics card capable of 1024x768 resolution 19 | 20 | For optimal performance, we recommend the following: 21 | 22 | - 4 GB of RAM or more 23 | - Dedicated SSD with at least 120 GB of available space 24 | - Graphics card capable of 1920x1080 resolution or higher 25 | 26 | Please note that helloSystem is not currently available for computers with ARM-based processors, although there are build instructions for Raspberry Pi. 27 | 28 | When reviewing or benchmarking helloSystem, it is important to note that virtual machines may not provide an accurate representation of the system's stability, feature set, and performance. Therefore, **we recommend that reviewers use real hardware** for these purposes. Running helloSystem on actual hardware will provide a more authentic experience and allow reviewers to test the system's capabilities in a more realistic environment. Additionally, using real hardware will help to ensure that the system's hardware support is properly evaluated. For these reasons, we strongly advise against conducting tests and benchmarks in a virtual environment, even though VirtualBox guest drivers are preinstalled. 29 | 30 | ## Installation 31 | 32 | Installing helloSystem is a relatively straightforward process. Follow these steps to install helloSystem on your system: 33 | 34 | 1. Download the helloSystem ISO file from the helloSystem website. 35 | 2. Burn the ISO file to a USB drive or DVD. 36 | 3. Insert the USB drive or DVD into your computer and boot from it. 37 | 4. Follow the on-screen instructions to install helloSystem. 38 | 39 | helloSystem is designed to be installed on a dedicated SSD, and for the sake of simplicity currently cannot be installed alongside other operating systems on the same disk. Additionally, if you are running helloSystem on a device with a UEFI firmware, you may need to disable Secure Boot in order to boot into helloSystem. 40 | 41 | If you encounter any issues during the installation process, please consult the helloSystem documentation or contact the [helloSystem discussion forum](https://github.com/helloSystem/hello/discussions/) for assistance. 42 | 43 | ## User Interface 44 | 45 | The six-part series on [Linux desktop usability](https://medium.com/@probonopd/make-it-simple-linux-desktop-usability-part-1-5fa0fb369b42) by helloSystem's founder eventually lead to the design and development of helloSystem. The series explored aspects of desktop usability, from user interface design to application packaging and distribution. The insights expressed in the series helped inform the design decisions behind helloSystem, with a focus on simplicity, ease of use, and discoverability. The intended result is a user-friendly and efficient operating system that is easy to use and customize, even for non-technical users. 46 | 47 | The helloSystem user interface is designed to be intuitive, functional, and discoverable, with a range of features and tools to meet the needs of both new and experienced users. Here are some key concepts: 48 | 49 | - **Command key** left to the spacebar: On systems with a Mac-style keyboard, the Command key is located to the left of the spacebar, which can be more comfortable for Mac users. When helloSystem is used with a PC keyboard, the Alt key functions as the Command key, being located in the same physical location on the keyboard. 50 | 51 | - **Global menu bar**: helloSystem features a global menu bar, which is a menu bar that is located at the top of the screen, rather than within the application window. This provides for a consistent user experience across applications, even if those applications are written in non-native frameworks such as Gtk or Electron. 52 | 53 | - **Keyboard layout and language autodetection**: When using a Mac or a [Raspberry Pi Keyboard and Hub](https://www.raspberrypi.com/products/raspberry-pi-keyboard-and-hub/), helloSystem will automatically detect the keyboard layout and language, removing the need to configure it manually. 54 | 55 | - **Menu search and launcher**: helloSystem includes a powerful menu search and launcher, which can be used to quickly find and launch applications, files, and menu commands. It is located in the top left corner of the global menu bar and can be a true productivity booster, as it allows the system to be operated virtually only by using the keyboard. 56 | 57 | - **Application bundles**: Applications on helloSystem are structured as self-contained bundles, which can be easily installed, removed, and updated. 58 | 59 | - **`launch` command using a database**: helloSystem uses a database to manage launch commands, rather than relying on traditional XDG desktop files, which will provide better functionality, e.g., for applications that can be freely moved around in the fileystem without the need to update `.desktop` files. 60 | 61 | - **Source code editability** for many Utilities: Many of the utilities included with helloSystem have their source code included and do not need to be compiled, making it easy for users to customize and contribute to the system. Right-click on an application icon and choose "Show Contents" to see and edit the source code. 62 | 63 | ## Features 64 | 65 | - **Resource efficiency**: helloSystem is designed to be lightweight and efficient, with moderate resource usage, making it suitable for use on a range of hardware configurations. Compare the RAM usage to other similar systems. 66 | 67 | - **Graphics and media support**: helloSystem includes a range of appliactions and features designed to support graphics artists, designers, videographers, makers with 3D printers, and other creative professionals, without requiring them to think much about the operating system. 68 | 69 | - **Under Construction**: The "Under Construction" section of the menu provides access to various utilities and tools that are currently in development, and are looking for contributors to help bring them to completion. helloSystem does not hide its open source nature, and invites power users to join the development fun. 70 | 71 | - **Zeroconf (mDNS-SD)**: helloSystem makes use of this technology throughout the system to advertise and browse network resources, like servers, printers, and the like. 72 | 73 | - **Create Live Media** utility: helloSystem includes a tool for creating live media, which can be used to create a bootable USB or DVD to try helloSystem without installing it on your system. It can also burn the latest, frequently released, experimental ISO builds directly to USB sticks. 74 | 75 | ## Particularities 76 | 77 | * Please refer to the global menu bar at the top of the screen in helloSystem as the "Menu", as those who have grown up using a Macintosh will likely feel right at home with this naming convention. Avoid terminology like "panel", as the target audience of helloSystem may not be familiar with it. Similarly, please refer to the "desktop", "documents", and "folders" rather than the "wallpaper", "files", and "directories". 78 | 79 | * The file manager in helloSystem, Filer, is intentionally kept simple and is aspiring to grow into a truly [spatial](https://arstechnica.com/gadgets/2003/04/finder/) file manager over time. Which means that every document and folder has one physical location on the screen, and one location only. When opening an empty folder, it will show a blank window. This is because there is nothing to display in an empty folder, much like how a text editor shows a blank window when opening a new text file. 80 | 81 | * helloSystem uses black text on white background. With the intoduction of modern graphical user interfaces, black text on white background (like paper, "WYSIWYG") was a revelation compared to the amber or green screens of MS-DOS PCs. 82 | 83 | * In helloSystem, there is no concept of "launchers." Instead, it uses symlinks to applications, which can be created by dragging and dropping an application from its folder to the desktop. Keep in mind that helloSystem aims to keep things simple and straightforward for switchers from the Mac, who don't have conceptions of "launchers". 84 | 85 | * The Dock is not used by default in helloSystem, although it is still available in `/System` for those who really need it. While the Dock was a later addition to the Mac OS X experience, helloSystem allows users to switch between applications like on Classic systems, saving precious screen real estate at the bottom of the screen. 86 | 87 | * In helloSystem, there is no unified control panel. Instead, there are individual preferences applications located in `/Applications/Preferences`. This is simpler and more similar to the control panels found in System 7. 88 | 89 | ## Support 90 | 91 | helloSystem is a community-driven project. If you encounter any issues or have questions about helloSystem, there are several resources available to help you get support and connect with the community: 92 | 93 | - **Official website**: The helloSystem website (https://hellosystem.github.io/) provides a range of resources and information about the operating system, including documentation for users and for developers. 94 | 95 | - **Issue tracker**: If you encounter a bug or have an issue with helloSystem, please submit a report to the issue tracker (https://github.com/helloSystem/ISO/issues) on the project's GitHub page. This is a great way to get help and connect with the development team and the broader helloSystem community. 96 | 97 | - **Discussions**: The helloSystem forum (https://github.com/helloSystem/hello/discussions/) provides a platform for users to connect with each other and discuss topics related to helloSystem, including troubleshooting, brainstorming, and development. 98 | 99 | - **IRC channel**: For more immediate assistance, you can join the helloSystem IRC channel (`#hellosystem`) on the [Libera.Chat](https://libera.chat/) network. This is a great way to connect with other users and developers in real time. Please stay in the channel for several days, as many contributors cannot be there 24/7. 100 | -------------------------------------------------------------------------------- /user/components.md: -------------------------------------------------------------------------------- 1 | # Getting to know the system 2 | 3 | helloSystem consists of the following key components, each of which are described in this section: 4 | 5 | 6 | ```{toctree} 7 | --- 8 | maxdepth: 2 9 | glob: true 10 | --- 11 | 12 | components/* 13 | ``` 14 | -------------------------------------------------------------------------------- /user/components/applications.md: -------------------------------------------------------------------------------- 1 | # Applications 2 | 3 | Most applications in helloSystem 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 languages such as PyQt5, because you can interactively edit the source code and test your changes. 4 | 5 | ![Viewing the contents of an application bundle](https://pbs.twimg.com/media/EoK9u7vXUAAJFPn?format=png) 6 | 7 | helloSystem comes with some applications out of the box, and some applications need to be downloaded before they can be used. 8 | 9 | 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. 10 | 11 | ```{toctree} 12 | --- 13 | maxdepth: 2 14 | glob: true 15 | --- 16 | 17 | applications/* 18 | ``` 19 | -------------------------------------------------------------------------------- /user/components/applications/falkon.md: -------------------------------------------------------------------------------- 1 | # Falkon 2 | 3 | __Falkon__ is the web browser that comes with helloSystem by default. 4 | 5 | ## Search shortcuts 6 | 7 | The following search shortcuts have been predefined: 8 | 9 | ### Search Engines 10 | 11 | * __`g`: Search Google.__ Example: `g Frankfurt` 12 | * __`d`: Search DuckDuckGo.__ Example: `d München` 13 | * __`sp`: Search StartPage.__ Example: `sp Hamburg` 14 | 15 | ### Encyclopedia 16 | 17 | * __`w`: Search Wikipedia.__ Example: `w Stuttgart` 18 | 19 | ### Computer related 20 | 21 | * __`man`: Search FreeBSD Man Pages.__ Example: `man ls` 22 | * __`bug`: Search FreeBSD Bugzilla.__ Example: `bug Falkon` 23 | * __`gh`: Search GitHub.__ Example: `gh PyQt5` 24 | * __`h`: Search helloSystem on GitHub.__ Example: `h keyboard` 25 | 26 | Of course you can customize these and add your own search shortcuts in Falkon. 27 | 28 | ## Automatic reloading of local pages 29 | 30 | Falkon automatically refreshes the page when a local HTML document is changed. 31 | This makes it ideal for dynamically previewing locally edited HTML pages. 32 | -------------------------------------------------------------------------------- /user/components/applications/iridium.md: -------------------------------------------------------------------------------- 1 | # Iridium 2 | 3 | __Iridium__ is an optional web browser that can be used on helloSystem. It is based on the Chromium browser. 4 | 5 | Upon first start of the Iridium browser, the following extensions are automatically installed from [https://chrome.google.com/webstore/](https://chrome.google.com/webstore/) to increase privacy and convenience: 6 | 7 | * __I don't care about cookies__: Tries to remove annoying cookie popups automatically. Visit [https://www.i-dont-care-about-cookies.eu](https://www.i-dont-care-about-cookies.eu) to learn more about this extension. Deactivate or uninstall this extension if you would like to see cookie popups 8 | * __uBlock Origin__: Tries to block unwanted advertising and tracking. Visit [https://github.com/gorhill/uBlock](https://github.com/gorhill/uBlock) to learn more about this extension. Deactivate or uninstall this extension if you would like to see advertising and allow trackers to track you. 9 | 10 | You can uninstall those extensions at any time from within Iridium. 11 | 12 | If you would like Iridium not to install those extensions from the Chrome Web Store in the first place, remove the files in `/usr/local/share/iridium/extensions/*.json` prior to launching Iridium for the first time. 13 | -------------------------------------------------------------------------------- /user/components/autostart.md: -------------------------------------------------------------------------------- 1 | # Autostart 2 | 3 | The __Autostart__ mechanism provides an easy way to automatically start applications whenever the computer is started (to be precise, when a user is logged into a graphical desktop session). Applications can be either `.app` bundles or `.AppDir` directories. 4 | 5 | * __System-wide autostart__: Place applications (or symlinks to applications) into the `/Applications/Autostart` folder to have them started for all users of the computer 6 | 7 | * ~__Per-user autostart__: Place applications (or symlinks to applications) into the `~/Applications/Autostart` folder (in your home folder) to have them started for all users of the computer. You can create the folder if it does not exist yet~ 8 | 9 | The `launch` command is invoked for each of those applications and launches the applications. 10 | -------------------------------------------------------------------------------- /user/components/filesystems.md: -------------------------------------------------------------------------------- 1 | # Filesystems 2 | 3 | helloSystem uses the OpenZFS for the boot disk. 4 | 5 | Additionally, the following filesystems are supported in helloSystem, but it cannot be started from those: 6 | 7 | * exFAT (Windows) _once available in quarterly packages_ 8 | * NTFS (Windows; read-write support) 9 | * EXT4 (Linux) _once available in quarterly packages_ 10 | * HFS+ (Macintosh) 11 | * XFS (SGI) 12 | 13 | Supported filesystems are automatically mounted by [automount](https://github.com/vermaden/automount). 14 | 15 | To see how they are mounted, open the Logs utility and attach a disk. 16 | -------------------------------------------------------------------------------- /user/components/preferences.md: -------------------------------------------------------------------------------- 1 | # Preferences 2 | 3 | helloSystem comes with the following preferences applications, each of which are described in this section: 4 | 5 | ```{toctree} 6 | --- 7 | maxdepth: 2 8 | glob: true 9 | --- 10 | 11 | preferences/* 12 | ``` 13 | -------------------------------------------------------------------------------- /user/components/preferences/boot-environments.md: -------------------------------------------------------------------------------- 1 | # Boot Environments 2 | 3 | _Boot Environments_ are bootable clones of snapshots of the working system. Boot Environments allow you to create a safe fallback Boot Environment before upgrading or making major changes to the system. 4 | 5 | Other applications may create Boot Environments automatically before performing critical operations such as major operating system upgrades. 6 | 7 | :::{warning} 8 | Boot Environments by default do not cover all locations, such as `/home` where your personal data is usually stored. 9 | ::: 10 | 11 | The __Boot Environments__ preferences application lets you view, create, remove, mount, and boot into Boot Environments. 12 | 13 | :::{note} 14 | Boot Environments functionality cannot be used when the system is running from Live media. It can only be used when the system has been installed to a disk. 15 | ::: 16 | 17 | ## Viewing Boot Environments 18 | 19 | Open the __Boot Environments__ preferences application. If you have a user password set, you will be asked to enter your credentials. Only users in the administrative group (`wheel`) can use the Boot Environments application by default. 20 | 21 | You will see the available Boot Environments. 22 | 23 | ## Creating Boot Environments 24 | 25 | To create a new Boot Environment, click {guilabel}`New...` and enter a name for the new Boot Environment. 26 | 27 | ## Removing Boot Environments 28 | 29 | Select a Boot Environment by clicking on it, and then press {guilabel}`Remove`. Note that you cannot remove the currently active Boot Environment. 30 | 31 | ## Mounting Boot Environments 32 | 33 | You can make available, or "mount", existing Boot Environments, e.g., in order to inspect them or to copy files from there. 34 | 35 | To do this, select a Boot Environment by clicking on it, and then press {guilabel}`Mount`. Note that you cannot mount the currently active Boot Environment since it is already mounted at `/`. 36 | 37 | The selected Boot Environment will be mounted, and a Filer window will be opened at the mountpoint of the Boot Environment. 38 | 39 | ## Booting into a Boot Environment 40 | 41 | Activate a Boot Environment by checking its checkbox, and then press {guilabel}`Restart...`. The computer will restart into the selected Boot Environment. 42 | 43 | You can also select which Boot Environment to start into from the bootloader. Starting with helloSystem 0.8.1, press the press the {kbd}`Backsapce` key on your keyboard as soon as the screen becomes grey. Then use the FreeBSD bootloader menu to choose a Boot Environment and to start the system. Note that choosing a Boot Environment this way does not change the default Boot Environment, and will affect the current boot only. 44 | 45 | ## More Information 46 | 47 | Advanced users can use the `bectl` command on the command line, which the __Boot Environments__ preferences application is using under the hood. 48 | 49 | For more information regarding Boot Environments, please refer to the [ZFS Boot Environments](https://bsd-pl.org/assets/talks/2018-07-30_1_S%C5%82awomir-Wojciech-Wojtczak_ZFS-Boot-Environments.pdf) presentation by Sławomir Wojciech Wojtczak. 50 | -------------------------------------------------------------------------------- /user/components/preferences/desktop.md: -------------------------------------------------------------------------------- 1 | # Desktop 2 | 3 | The __Desktop__ preferences application allows you to customize the behavior of your computer's desktop. 4 | 5 | ## Background 6 | 7 | In this section of the __Desktop__ preferences application, you can select a background color and an optional background image. If an image is selected, you can choose how it should be scaled on the screen. 8 | 9 | ## Label Text 10 | 11 | In this section of the __Desktop__ preferences application, you can select a font and color for the text beneath icons on the desktop. 12 | 13 | ## Advanced 14 | 15 | Under the {guilabel}`advanced` tab of the __Desktop__ preferences application, advanced users can adjust additional aspects of the behavior of the desktop. Most users should leave the defaults. This tab may go away in a future version. 16 | -------------------------------------------------------------------------------- /user/components/preferences/keyboard.md: -------------------------------------------------------------------------------- 1 | # Keyboard 2 | 3 | The __Keyboard__ preferences application lets you change the keyboard layout (language) of your attached keyboard, and allows you to set which physical key should act as your {kbd}`⌘` (command) key. It also lets you disable the {kbd}`Caps Lock` key. 4 | 5 | :::{note} 6 | The keyboard layout (language) gets set automatically during system startup if an official Raspberry Pi keyboard is attached or the system is running on Macintosh hardware, which has the `prev-lang:kbd` EFI key set. 7 | ::: 8 | 9 | ## Setting the keyboard layout 10 | 11 | Simply click on a language (keyboard layout). The change is effective immediately. 12 | 13 | ## Selecting a physical key to act as ⌘ (command) 14 | 15 | Swapping the keys will result in the key left from the spacebar to act as the {kbd}`⌘` (command) key (like switchers from the Mac would expect) and therefore is the default. 16 | 17 | __If a PC keyboard is attached__, you can select the {guilabel}`Use the Alt key as ⌘` checkbox. This will swap the {kbd}`Ctrl` and {kbd}`Alt` keys. 18 | 19 | __If an Apple keyboard is attached__, you can select the {guilabel}`Use the ⌘ key for menu shortcuts` checkbox. This will swap the {kbd}`alt ⌥` and {kbd}`cmd ⌘` keys. 20 | 21 | If you prefer the keys not be swapped, simply uncheck the respective checkbox. The change is effective immediately. 22 | 23 | ## Disabling the Caps Lock key 24 | 25 | You can select the "Disable the Caps Lock key" checkbox. This will disable the Caps Lock key. The change is effective immediately. 26 | -------------------------------------------------------------------------------- /user/components/preferences/sharing.md: -------------------------------------------------------------------------------- 1 | # Sharing 2 | 3 | The __Sharing__ preferences application lets you make your computer accessible from the network. 4 | 5 | ![Sharing.app](https://pbs.twimg.com/media/EoK8buxXYAIdtvJ?format=png) 6 | 7 | ## Computer Name 8 | 9 | The __Computer Name__ (hostname) is displayed. You can change it. Changes in the Computer Name will take effect upon restarting the computer. 10 | 11 | ## Remote Login 12 | 13 | Check the {guilabel}`Remote Login` checkbox to make your computer accessible over ssh. 14 | 15 | ## Screen Sharing 16 | 17 | Check the {guilabel}`Screen Sharing` checkbox to make the screen of your computer accessible through VNC over ssh and advertise it on the network. This allows another user who has an account on your computer to view the screen, and to control the computer as if they were sitting in front of it. This can be helpful, e.g., for getting help from colleagues. The {guilabel}`Screen Sharing` checkbox will automatically be unchecked when the computer is restarted or after a connection has been made and has ended. 18 | 19 | ## Accessing the screen of remote computers 20 | 21 | ## Accessing the screen of a remote computer that has Screen Sharing enabled 22 | 23 | If Screen Sharing is active on the remote computer, then you can use [SSVNC](http://www.karlrunge.com/x11vnc/ssvnc.html) (available for Windows, Mac OS X, and various Unix-like systems) to access the machine over the local area network. 24 | 25 | In SSVNC please do: 26 | 27 | * Under {guilabel}`VNC Host_Display` please enter: `:0` 28 | * {guilabel}`Options...` -> Check the {guilabel}`Use SSH` box and the {guilabel}`Unix Username & Password` box 29 | * Under {guilabel}`Unix Username` enter the username you have set when you installed helloSystem 30 | * Under {guilabel}`Unix Password` enter the password you have set when you installed helloSystem 31 | 32 | ## Accessing the screen of a remote computer that has Remote Login enabled 33 | 34 | If Screen Sharing is not active but Remote Login is active on the remote computer, then you can connect over the local area network and enable Screen Sharing as follows. Replace `user` with your username on the remote computer, and `FreeBSD.local.` with the hostname of the remote computer: 35 | 36 | ```console 37 | $ ssh -t -L 5900:localhost:5900 user@FreeBSD.local. 'x11vnc -display :0 -auth /home/user/.Xauthority -once -localhost' 38 | ``` 39 | 40 | Log into the remote computer. Then start the Remote Desktop client as follows: 41 | 42 | ```console 43 | $ ssvncviewer localhost 44 | ``` 45 | 46 | You should now be able to see and operate the screen. 47 | -------------------------------------------------------------------------------- /user/components/preferences/shortcuts.md: -------------------------------------------------------------------------------- 1 | # Shortcut Keys 2 | 3 | :::{note} 4 | The Shortcut Keys preferences application has been removed following the switch to KWin, which comes with `kglobalaccel`. This area still needs work. 5 | ::: 6 | 7 | The {guilabel}`Shortcut Keys` preferences application lets you view and edit system-wide keyboard shortcuts. 8 | 9 | 10 | :::{note} 11 | The left {kbd}`Ctrl` and {kbd}`Alt` keys are swapped in helloSystem by default to make shortcuts feel welcoming to switchers coming from the Mac. 12 | ::: 13 | 14 | A __shortcut__ is a key or key combination you can press to invoke a defined action on your computer. Shortcuts can be defined by applications (per-application shortcuts), or can affect the whole system (system-wide shortcuts). 15 | 16 | :::{note} 17 | The Shortcut Keys preferences application lets you view and edit system-wide keyboard shortcuts only, not per-application shortcuts. Some applications contain similar functionality inside the respective application to view and edit per-application keyboard shortcuts. 18 | ::: 19 | 20 | ## The ⌘ key 21 | 22 | The {kbd}`⌘` key, also known as __Command__, is the key left to the spacebar on helloSystem, unless you have configured your system differently. 23 | 24 | :::{note} 25 | Non-native software may refer to the Command key as "Ctrl". This is a known cosmetic issue. 26 | ::: 27 | 28 | ## Default shortcuts 29 | 30 | Open the {guilabel}`Shortcut Keys` preferences application to view the default system-wide shortcuts. 31 | 32 | Notable default shortcuts include: 33 | 34 | * Press {kbd}`⌘` + {kbd}`Space` to __search in the Menu__ (e.g., to launch applications or to execute commands in the frontmost application) 35 | * Press {kbd}`Ctrl` + {kbd}`⌘` + {kbd}`Esc` and click on an application window to __forcefully quit an application__ that is malfunctioning 36 | * Press {kbd}`⌘` + {kbd}`⇧` + {kbd}`3` or the {kbd}`PrtScn` key on your keyboard to __take a screenshot__ 37 | * Press {kbd}`⌘` + {kbd}`⇧` + {kbd}`H` to go to the Home folder 38 | * Press {kbd}`⌘` + {kbd}`⇧` + {kbd}`A` to go to the Applications folder 39 | * Press {kbd}`⌘` + {kbd}`⇧` + {kbd}`U` to go to the Utilities folder 40 | * Press {kbd}`Ctrl` + {kbd}`⌘` + {kbd}`T` to open a Terminal 41 | * Press {kbd}`Ctrl` + {kbd}`⌘` + {kbd}`I` to open the internet browser 42 | 43 | This list is not exhaustive. 44 | 45 | ## Viewing shortcuts 46 | 47 | For a complete list of system-wide shortcuts, please open the {guilabel}`Shortcut Keys` preferences application to view the default shortcuts. 48 | 49 | ## Editing shortcuts 50 | 51 | Use the buttons in the {guilabel}`Shortcut Keys` preferences application to add, remove, and modify system-wide shortcuts. 52 | -------------------------------------------------------------------------------- /user/components/preferences/wireless-networks.md: -------------------------------------------------------------------------------- 1 | # Wireless Networks 2 | 3 | The {guilabel}`Wireless Networks` preferences application lets you connect to wireless local area networks (WLANs). 4 | 5 | It is possible to use more than one wireless network card. 6 | 7 | :::{note} 8 | Please consider using the Hardware Probe utility in case your network card is not detected by the Wireless Networks preferences application. 9 | ::: 10 | -------------------------------------------------------------------------------- /user/components/system.md: -------------------------------------------------------------------------------- 1 | # System components 2 | 3 | helloSystem comes with the following system components, each of which are described in this section: 4 | 5 | ```{toctree} 6 | --- 7 | maxdepth: 2 8 | glob: true 9 | --- 10 | 11 | system/* 12 | ``` 13 | -------------------------------------------------------------------------------- /user/components/system/dock.md: -------------------------------------------------------------------------------- 1 | # Dock 2 | 3 | The __Dock__ is a quick way to launch the most commonly used applications, and a way to see which applications are running at a glance. 4 | 5 | It typically sits at the bottom of the screen. 6 | 7 | As of helloSystem 0.8.0, the Dock is not started automatically anymore, but you can run it by double-clicking its icon in /System. You can also put a symlink into /Applications/Autostart if you like (`sudo ln -s /System/Dock.app /Applications/Autostart/`), or start it programmatically with `launch Dock`. 8 | 9 | ## Launching applications 10 | 11 | To launch an application, click on it in the Dock. 12 | 13 | ## Seeing running applications 14 | 15 | Running applications are marked with a dot below the application icon in the Dock. 16 | 17 | ## Keeping applications in the Dock 18 | 19 | To keep an application in the Dock even if it is not running, click on its icon in the Dock with the right mouse key, and select "Pin" from the context menu. 20 | -------------------------------------------------------------------------------- /user/components/system/filer.md: -------------------------------------------------------------------------------- 1 | # Filer 2 | 3 | __Filer__ is the application that you can use to manage objects like files, folders, and applications on your computer. 4 | 5 | Filer can perform typical tasks of a file manager: 6 | * Open files and folders 7 | * Create, move, and delete files and folders 8 | 9 | In helloSystem, many tasks are done in the Filer that would require extra tools in other operating systems. For example, you can use the Filer to 10 | * Launch applications (instead of using a dedicated launcher) 11 | * Make applications available to the system (instead of using a package manager or compiling from source) 12 | * Remove applications (instead of using a package manager) 13 | * Accessing files on remote computers (instead of using a dedicated application that can access files over ssh/sftp) 14 | 15 | ## Launching applications 16 | 17 | To launch an application, double-click it in Filer (you can also use the `⌘O` shortcut to open an application, or press `⌘↓`). In case you double-click on a binary that is lacking the execute permission, a dialog will ask you whether you would like to make the binary executable. 18 | 19 | ## Making applications available to the system 20 | 21 | Applications for helloSystem typically come as application bundles. An application bundle looks like a file but is actually stored as a directory on disk. To make an application available to the system, simply move or copy it to one of the well-known locations for applications, such as `/Applications` for system-wide applications, or `~/Applications` (in your home directory) for per-user applications. 22 | 23 | In addition to applications specifically offered for helloSystem, advanced users can use the tools provided by FreeBSD to compile applications from the ports tree, and/or to install FreeBSD packages. 24 | 25 | ## Removing applications 26 | 27 | To remove an application from the system, move it to the Trash. 28 | 29 | ## Accessing files on remote computers 30 | 31 | Computers on the local area network that are offering access via SFTP are automatically discovered and are shown in the "Network" area of Filer. Double-click on a network directory to access it. You will be asked to provide valid credentials (username, password) of an account on the remote computer. For this to work, computers need to provide SFTP services and announce them over dns-sd (Zeroconf, Bonjour). 32 | 33 | It is also possible to access files on computers that are not on the local area network. To do so, enter `sftp://hostname.tld` in the address bar of Filer and press the Enter key. 34 | 35 | ## Keyboard shortcuts 36 | 37 | In addition to the shortcuts documented in the menus, the following shortcuts exist when Filer is running in Spatial Mode (which is the default on helloSystem): 38 | 39 | * `⌘↓`: Open the selected application, file, or folder 40 | * `⌘↑`: Go up one folder 41 | * `⌘⇧O`: Open the selected application, file, or folder, and close the current window 42 | * `⌘⇧↓`: Open the selected application, file, or folder, and close the current window 43 | * `⌘⇧↑`: Go up one folder, and close the current window 44 | -------------------------------------------------------------------------------- /user/components/system/launch.md: -------------------------------------------------------------------------------- 1 | # launch 2 | 3 | ```{epigraph} 4 | "It’s not just what it looks like and feels like. Design is how it works." 5 | 6 | -- Steve Jobs 7 | ``` 8 | 9 | The {command}`launch` command is used to launch graphical applications on helloSystem. When you select an application from the [Menu](menu.md) or the [Dock](dock.md), then the {command}`launch` command is invoked to actually launch the application. 10 | 11 | :::{hint} 12 | As an end user who is using the graphical user interface exclusively, you will not need to interact with the {command}`launch` command directly and can skip this section. 13 | ::: 14 | 15 | ## Background 16 | 17 | On UNIX systems, applications are typically launched by entering the name of the executable file, which is searched in a fixed list of directories determined by the `$PATH` environment variable. 18 | 19 | Many graphical desktop environments use `.desktop` files to integrate applications with the system. While this has traditionally worked well for installed applications, it does not work well for dynamically changing applications that are moved in the filesystem, such as `.app` bundles or `.AppDir` directories. Also, it does not handle multiple versions of the same application gracefully. Hence, helloSystem uses the {command}`launch` command to launch graphical applications. This has the following advantages: 20 | 21 | * You do not need to know the path to the application to be launched, even if the application is not on the `$PATH` 22 | * If multiple versions of an application are available on the system, the most recent one will be launched automatically (unless specified otherwise by the user) __(to be implemented)__ 23 | * If something goes wrong and the application cannot be launched, then a graphical error message will be shown on the screen 24 | 25 | ![Graphical error message if something goes wrong](https://pbs.twimg.com/media/EoLKXl7WEAAWCtQ?format=png) 26 | 27 | ## Using the launch command 28 | 29 | Whenever possible, graphical applications should be launched through the {command}`launch` command on helloSystem. 30 | 31 | There are several ways in which the {command}`launch` command can be invoked: 32 | 33 | * `launch /Applications/Filer.app` 34 | * `launch Filer.app` 35 | * `launch Filer` 36 | 37 | Note that capitalization can have subtle effects: 38 | 39 | * `launch audacity` launches `audacity` from the `$PATH` if it exists anywhere on the `$PATH` 40 | * `launch Audacity` launches e.g., `/Applications/Audio/Audacity.app/Audacity` if it exists there or in other well-known application locations (because no `Audacity` exists anywhere on the `$PATH`) 41 | -------------------------------------------------------------------------------- /user/components/system/menu.md: -------------------------------------------------------------------------------- 1 | # Menu 2 | 3 | The menu bar at the top of the screen lets you perform, among others, the following functions: 4 | 5 | * Get information about your computer 6 | * Hide and unhide windows 7 | * Launch applications 8 | * Shut down your computer 9 | * Search in application menus 10 | * Search for documents and folders on your computer 11 | * Open folders at certain paths 12 | * Perform calculations 13 | * See date and time 14 | 15 | ## Getting computer information 16 | 17 | Select "About This Computer" from the "System" menu. 18 | 19 | ## Managing windows 20 | 21 | Select "Hide all" to minimize all windows to the Dock. 22 | 23 | Select "Unhide all" to get all windows back on screen. 24 | 25 | ## Launching applications 26 | 27 | Select an application from "Applications", "Utilities", or "Preferences" in the "Applications" menu. 28 | 29 | A quicker way to launch an application is to press {kbd}`Alt+Space`, enter a few characters of the application name, select one of the matches from the list, and press the Enter key. 30 | 31 | ## Shutting down 32 | 33 | To shut down your computer, select "Log Out" from the "System" menu, then click "Shut Down". You can also choose "Restart" if you want to restart your computer, or "Log Out" if you would like to log out of the current graphical session. 34 | 35 | ## Searching in application menus 36 | 37 | Click on "Search" in the menu bar, or press {kbd}`Command+Space`. Then enter a few characters of the menu entry you would like to execute, select one of the matches from the list, and press the Enter key. 38 | 39 | ## Searching for documents and folders on your computer 40 | 41 | Click on "Search" in the menu bar, or press {kbd}`Command+Space`. Then enter a few characters of the document or folder name, select one of the matches from the list, and press the Enter key. 42 | 43 | ## Opening folders at certain paths 44 | 45 | Click on "Search" in the menu bar, or press {kbd}`Command+Space`. Then enter `/` or `~` followed by a folder name, select one of the matches from the list, and press the Enter key. 46 | 47 | ## Performing calculations 48 | 49 | Starting with helloSystem 0.8.2, you can perform calculations using the Menu. Click on "Search" in the menu bar, or press {kbd}`Command+Space`. Then enter a mathematical statement like `2+2` or `sqrt(2)`. The result of the calculation will be shown in the menu. See these [examples](https://github.com/Qalculate/libqalculate#features) for the type of calculations that can be performed. 50 | 51 | ## Date and time 52 | 53 | Date and time in your current timezone are displayed at the right hand side of the menu bar. 54 | -------------------------------------------------------------------------------- /user/components/utilities.md: -------------------------------------------------------------------------------- 1 | # Utilities 2 | 3 | helloSystem comes with the following utilities, each of which are described in this section: 4 | 5 | ```{toctree} 6 | --- 7 | maxdepth: 2 8 | glob: true 9 | --- 10 | 11 | utilities/* 12 | ``` 13 | -------------------------------------------------------------------------------- /user/components/utilities/calculator.md: -------------------------------------------------------------------------------- 1 | # Calculator 2 | 3 | The __Calculator__ application is a simple graphic calculator application. 4 | 5 | Actually, it is a [Calculator Construction Set](https://www.folklore.org/StoryView.py?story=Calculator_Construction_Set.txt). 6 | -------------------------------------------------------------------------------- /user/components/utilities/calendar.md: -------------------------------------------------------------------------------- 1 | # Calendar 2 | 3 | The __Calendar__ utility is a simple calendar. 4 | 5 | This application serves as an example how easily Qt widgets can be used from Python. 6 | Users are invited to look at and play with the source code. 7 | -------------------------------------------------------------------------------- /user/components/utilities/create-live-media.md: -------------------------------------------------------------------------------- 1 | # Create Live Media 2 | 3 | A __Live Medium__ is a storage device that can be used to start your computer with the helloSystem without having to install helloSystem to the internal storage of the computer. It allows you to try out helloSystem without making any changes to the software installed on your computer. Almost all functionality of helloSystem is available in Live mode, with very few exceptions. Changes being made, including files created, will be discarded when the system is shut down or restarted. 4 | 5 | The __Create Live Media__ utility provides an easy and convenient way to create bootable Live Media on devices such as USB sticks. It downloads and writes Live ISOs to devices in one go. 6 | 7 | ![Create Live Media](https://user-images.githubusercontent.com/2480569/100794701-3bb03900-341e-11eb-8c18-e45fc68b7dbe.png) 8 | 9 | This is useful if you are running helloSystem and would like to write a newer (or experimental) version of the system to a bootable storage device. 10 | 11 | ## Prerequisites 12 | 13 | In order to create a Live medium, you need 14 | * A computer running any version of helloSystem with the __Create Live Media__ utility 15 | * A fast internet connection (a typical download is around 2 GiB) 16 | * A suitable external storage device, e.g., a USB3 device. USB2 devices can be used but performance may be degraded. On some systems, other storage media such as SD cards or microSD cards can be used. Consult the documentation that came with your computer to determine which type of media can be used to start your computer. 17 | 18 | :::{note} 19 | The **Create Live Media** utility cannot be used on other operating systems such as Windows, Linux, or macOS. 20 | 21 | If you would like to create Live Media for helloSystem using one of those operating systems, you can use applications that can write images to USB storage devices, such as [balenaEtcher](https://www.balena.io/etcher/). 22 | ::: 23 | 24 | ## Downloading and writing Live Media 25 | 26 | The __Create Live Media__ utility downloads and writes a Live ISO image in one go to a storage medium. Open the __Create Live Media__ utility and follow the instructions on screen. 27 | 28 | :::{warning} 29 | The **Create Live Media** utility will overwrite the entire contents of the selected device, including all of its pre-existing partitions. Take extra caution when selecting the target device. 30 | 31 | This operation cannot be undone. 32 | ::: 33 | 34 | Once the image has been written to the device successfully, you can restart your computer to start from the Live Medium, or remove the device and insert it into another computer to start that computer from the Live Medium. 35 | -------------------------------------------------------------------------------- /user/components/utilities/hardware-probe.md: -------------------------------------------------------------------------------- 1 | # Hardware Probe 2 | 3 | The __Hardware Probe__ utility collects hardware details of your computer and can anonymously upload them to the public database at [bsd-hardware.info](https://bsd-hardware.info/?d=helloSystem). 4 | 5 | ![](https://user-images.githubusercontent.com/2480569/103484839-12564480-4df2-11eb-8c57-d6ee6ef48e2b.png) 6 | 7 | This can help users and operating system developers to collaboratively debug hardware related issues, check for operating system compatibility and find drivers. 8 | 9 | You will get a permanent probe URL to view and share collected information. 10 | 11 | ## Data Privacy 12 | 13 | The Hardware Probe utility can upload the hardware probe to the hardware database. The probe will be published publicly under a permanent URL to view the probe. 14 | 15 | Private information (including the username, machine's hostname, IP addresses, MAC addresses, UUIDs and serial numbers) is NOT uploaded to the database. 16 | 17 | The tool uploads 32-byte prefix of salted SHA512 hash of MAC addresses/UUIDs and serial numbers to properly identify unique computers and hard drives. All the data is uploaded securely via HTTPS. 18 | 19 | :::{note} 20 | By using this utility to upload your hardware probe, you agree that information about your hardware will be uploaded to a publicly visible database. 21 | 22 | Do not use this utility if you do not agree with this. 23 | ::: 24 | 25 | By uploading your hardware probe you confirm uploading of 32-byte prefix of salted SHA512 hash of MAC addresses and serial numbers to prevent duplication of computers in the database. 26 | 27 | The web service and the database are operated by linux-hardware.org. The authors of the graphical Hardware Probe utility are not associated with the operator of the web service. Please contact https://linux-hardware.org/index.php?view=contacts in case of questions and in case you wish accidentally submitted probes to be removed from the database. 28 | -------------------------------------------------------------------------------- /user/components/utilities/install.md: -------------------------------------------------------------------------------- 1 | # Install helloSystem 2 | 3 | Once you have tried out helloSystem from the live medium, you may want to install the system to the hard disk in your computer, or an externally attached storage device. 4 | 5 | The __Install helloSystem utility lets you install helloSystem on your computer from a running Live system. 6 | 7 | :::{note} 8 | The utility is called **Install helloSystem** to signify that helloSystem contains a largely unmodified FreeBSD core operating system. It might be renamed "Install helloSystem" in the future. 9 | ::: 10 | 11 | ![Install FreeBSD](https://user-images.githubusercontent.com/2480569/93003377-7d77c480-f53e-11ea-9e2d-aed1b41a17df.png) 12 | 13 | When you install helloSystem using the __Install helloSystem utility, the installed system will behave like the Live system in most aspects. 14 | 15 | ## Prerequisites 16 | 17 | * A bootable helloSystem Live Medium 18 | * A computer capable of starting from the Live Medium 19 | * An internal or external storage device with 8 GB of storage space. More space is highly recommended to allow for adding applications and documents 20 | 21 | ## Installing helloSystem 22 | 23 | Start your computer from a helloSystem Live Medium. Open the __Install helloSystem utility and follow the instructions on screen. 24 | 25 | The installer starts by presenting a summary. Click on "Continue". To install the software, you must agree to the terms of the software license agreement. Click on "Continue" to proceed. Click on a destination disk on which the operating system should be installed. A warning will inform you that the entire disk will be erased. Confirm whether you want to do this by clicking on the appropriate button. 26 | 27 | :::{warning} 28 | The **Install helloSystem** utility will overwrite the entire contents of the selected device, including all of its pre-existing partitions. Take extra caution when selecting the target device. 29 | 30 | This operation cannot be undone. 31 | ::: 32 | 33 | If you are really sure that you have selected the correct device, click "Continue". 34 | 35 | In the next step, you will create an account for the main user of the computer. The information entered here is used to identify the main user of the computer. This user will have administrative permissions (will be member of the `wheel` group). 36 | 37 | * In the field __Full Name__, enter your first name(s), followed by a blank, followed by your last name. Example: `John Doe`. This field can be left blank if you prefer not to provide your full name 38 | * The field __Username__ will be automatically populated with a suggested username. It must not contain any special characters such as blanks. You can override the suggested default if you like. Example: `jdoe` 39 | * Enter a password into the __Password__ field. Repeat the same password in the __Retype Password__ field. These fields can be left blank if you prefer not to use a password, but this will mean that anyone with access to your computer will be able to log in, and you will not be able to log in over the network 40 | * The field __Computer Name__ will be automatically populated with a suggested computer name (hostname). This name will be used to identify your computer on the local area network. It must not contain any special characters such as blanks. You can override the suggested default if you like. Example: `Johns-TravelMate-B117-M` 41 | * Check the checkbox __Enable users to log in over the network (ssh)__ if you would like to allow accessing the computer remotely. By default, this requires a password to be set for the computer account 42 | * Check the checkbox __Set time zone based on current location__ if you would like timezone on the installed system to be set automatically. This feature requires an active internet connection 43 | * Check the checkbox __Disable swap (recommended for USB sticks and SD cards)__ if you are installing the operating system to a medium on which no swap space should be used. This may be advisable on small system disks, and when installing to slower flash based media such as USB sticks and SD cards 44 | 45 | Click "Continue" to proceed. The system will be installed to the selected disk. This process typically takes a couple of minutes depending on your system configuration, during which a progress bar will be shown. 46 | 47 | You can click on "Installer Log" at any time to see a detailed log of the actions performed by the installer and details on any possible errors. 48 | 49 | Once the installation has completed, remove the Live medium from your computer and click the "Restart" button to start the newly installed system. 50 | -------------------------------------------------------------------------------- /user/components/utilities/mountarchive.md: -------------------------------------------------------------------------------- 1 | # mountarchive 2 | 3 | The __`mountarchive`__ tool makes archives (like `.zip`, `.tar.gz`, and `.tar.bz2` accessible in the Filer without having to extract them. 4 | 5 | For example, if you double-click a zip file called `plugin.video.invidious-0.5.3.zip` on your desktop, it will be mounted and a Filer window will be opened at its mountpoint, e.g., `/var/run/user/1001/_home_user_Desktop_plugin.video.invidious-0.5.3.zip`. 6 | -------------------------------------------------------------------------------- /user/components/utilities/remote-assistance.md: -------------------------------------------------------------------------------- 1 | # Remote Assistance 2 | 3 | The __Remote Assistance__ utility allows a peer on the Internet to access and control your computer using the encrypted peer-to-peer Tox protocol. This can be helpful, e.g., to receive help from a friend. 4 | 5 | :::{warning} 6 | Running the **Remote Assistance** utility will give your peer access to the screen, mouse, and keyboard of your computer, and read-write to any ports that may be open on your machine. Only share the ID with people you trust. 7 | ::: 8 | 9 | ## Receiving Remote Assistance 10 | 11 | To get help form a peer, open the Remote Assistance utility. Once a connection has been made, a long string (the ID) is shown on the screen. This string has also been copied to the clipboard. Give that string to your remote peer, e.g., by pasting it into a mail or chat window. 12 | 13 | Once your peer has successfully connected, they will be able to see and operate anything on your screen, and to connect to any ports that may be open on your machine. 14 | 15 | ## Giving Remote Assistance 16 | 17 | As the remote peer (the person providing help), open the Remote Assistance utility, and select "Give Assistance" from the File menu. Paste the long string (the ID) you received into the text box and click "Connect". 18 | 19 | Once the connection has been made, you will be able to see and operate the screen of the other machine. 20 | 21 | ## About the Tox protocol 22 | 23 | The __Remote Assistance__ application uses the Tox protocol to tunnel traffic. Tox is a peer-to-peer protocol that offers end-to-end encryption. The stated goal of the project is to provide secure yet easily accessible communication for everyone. 24 | -------------------------------------------------------------------------------- /user/components/utilities/sticky-notes.md: -------------------------------------------------------------------------------- 1 | # Sticky Notes 2 | 3 | The __Sticky Notes__ allows you to keep notes on your computer. 4 | 5 | Right-click on its icon in the menu bar to add new notes, show all notes, and change preferences. 6 | -------------------------------------------------------------------------------- /user/components/utilities/update.md: -------------------------------------------------------------------------------- 1 | # Update 2 | 3 | Once you have installed the system to the hard disk in your computer, or an externally attached storage device, you may want to keep it recent by running the __Update__ utility from time to time. 4 | 5 | :::{note} 6 | This utility is currently in **Developer Preview** status and is intended for developers and testers. Only use it if you have a backup of your system or if you are running on a test system that you can set up from scratch if needed. 7 | ::: 8 | 9 | This utility 10 | * Creates a new Boot Environment (bootable partial snapshot). __This is not a full replacement for a backup__ but should allow you to roll back to the state before the update, should something go wrong 11 | * Updates the FreeBSD operating system components (kernel and userland) 12 | * Updates all FreeBSD Packages 13 | * Currently does _not_ update any applications that came with helloSystem as native application bundles 14 | 15 | ![](https://user-images.githubusercontent.com/2480569/137626617-ffa339e5-5633-4fa4-84a5-9dd9c7f4b966.png) 16 | 17 | ## Testing 18 | 19 | Please follow this exact procedure when testing the Update utility: 20 | 21 | * Install a helloSystem 0.7.0 pre-release build to hard disk. 22 | * Open QTerminal and run `sudo pkg lock --yes automount slim dejavu liberation-fonts-ttf`. This step is __important__ because otherwise the update will overwrite carefully crafted helloSystem customizations. (There may be more packages that need to be locked as well.) 23 | * Run the __Update__ utility and follow the on-screen instructions. 24 | * Once the update has completed, restart your computer to make full use of the updated software. 25 | * Run the __Boot Environments__ preferences application and check that there is a boot environment that you can switch back to in the case you are not satisfied with the updated system. 26 | 27 | Please submit any problems you might be running into to [this issue](https://github.com/helloSystem/Utilities/issues/33). 28 | 29 | Thanks for testing the Update utility. 30 | -------------------------------------------------------------------------------- /user/components/windows.md: -------------------------------------------------------------------------------- 1 | # Windows 2 | 3 | helloSystem provides a graphical desktop experience that should be familiar to users of existing desktop operating systems. 4 | 5 | ## Traffic lights 6 | 7 | Windows contain three buttons, called "traffic lights": 8 | 9 | * __Red__: Click this button to close the window 10 | * __Yellow__: Click this button to hide (minimize) the window. To make the window appear again, click on its icon in the Dock, or select "Unhide all" from the System menu 11 | * __Green__: Click this button to make the window use the full screen real estate available (maximize). Click this button again to resize the window to its previous size 12 | 13 | ## Resizing windows 14 | 15 | Place the mouse cursor in any edge of the window. The cursor will change. Click and drag the mouse to resize the window. 16 | 17 | Alternatively, click in the window title with the right-hand mouse button and select "Resize" from the menu, then drag the mouse to resize the window. 18 | -------------------------------------------------------------------------------- /user/feedback.md: -------------------------------------------------------------------------------- 1 | # Providing feedback 2 | 3 | ## Sharing your experience 4 | 5 | If you would share your experience with helloSystem on twitter, use the [`#helloSystem` hashtag](https://twitter.com/hashtag/helloSystem). 6 | 7 | ## Discussing ideas and wishlist items 8 | 9 | Please check [https://github.com/helloSystem/hello](https://github.com/helloSystem/hello) first, including the [wiki](https://github.com/helloSystem/hello/wiki). Feel free to discuss ideas and wishlist items at [https://github.com/helloSystem/hello/issues](https://github.com/helloSystem/hello/issues), but please do keep in mind that in order to achieve the intended goal of simplicity, the team needs to say "no" to most wishlist items that do not further that goal. 10 | 11 | ## Discussion forum 12 | 13 | Please see our [GitHub Discussions](https://github.com/helloSystem/hello/discussions) and do not hesitate to post your ideas, questions, and show us what you are doing with helloSystem in th "Show&Tell" category. 14 | 15 | ## Chat 16 | 17 | You can meet other helloSystem users and developers in the `#helloSystem` [Internet Relay Chat](https://en.wikipedia.org/wiki/Internet_Relay_Chat) channel at `irc.libera.chat`. 18 | 19 | Alternatively, you can join [`#helloSystem:matrix.org`](https://matrix.to/#/#helloSystem:matrix.org) from any Matrix client (such as the Element web-based Matrix client). This Matrix channel is bridged to the IRC channel. Joining via Matrix has the advantage that you will see responses that you may have received while you were offline. So after asking a question, you can come back in a day or so to see if there were any responses. 20 | 21 | In any case, please stay in the channel for a few days and do not expect to receive answers immediately, since we are all volunteers. 22 | -------------------------------------------------------------------------------- /user/getting-started.md: -------------------------------------------------------------------------------- 1 | # Getting started 2 | 3 | ## System requirements 4 | 5 | * 2 GHz dual core Intel/AMD 64-bit processor 6 | * 2 GiB RAM system memory (4 GiB recommended; before 0.7.0: 4 GiB minimum) 7 | * VGA capable of 800x600 screen resolution (1024x768 or more recommended) 8 | * Either a CD/DVD drive or a USB port for booting the installer media 9 | * On non-Macintosh hardware, a [Raspberry Pi Keyboard and Hub](https://www.raspberrypi.com/products/raspberry-pi-keyboard-and-hub/) is recommended as it allows the keyboard and system language to be detected automatically if it is attached while the system is starting up. On Macintosh hardware, the `prev-lang:kbd` EFI variable is usually set and is used to detect the keyboard and system language. Note that the key left to the space bar is used as the Command key (Alt key on PC keyboards, Apple key on Apple keyboards). 10 | 11 | Please refer to [FreeBSD Hardware Compatibility](https://www.freebsd.org/doc/en_US.ISO8859-1/books/faq/hardware.html) for more information on individual components. 12 | 13 | ## Downloading 14 | 15 | The latest helloSystem release ISO image is available for download here: 16 | 17 | [![GitHub release (latest by date)](https://img.shields.io/github/v/release/helloSystem/ISO)](https://github.com/helloSystem/ISO/releases/latest) 18 | 19 | Experimental and pre-release images are available for download here: 20 | 21 | [![GitHub release (latest SemVer including pre-releases)](https://img.shields.io/github/v/release/helloSystem/ISO?include_prereleases)](https://github.com/helloSystem/ISO/releases) 22 | 23 | :::{important} 24 | Experimental images get built automatically whenever source code is committed. Not every build is tested. Builds marked as "Pre-Release" are strictly for developers, may be broken and may not even boot. 25 | ::: 26 | 27 | ## Creating Live Media 28 | 29 | The ISO file needs to be written to a device, e.g., to a USB stick, in order to a computer being able to start from it. This will overwrite and destroy all data on that device. 30 | 31 | If you are already running helloSystem, then you can use the built-in __Create Live Media__ utility to download and write live media. 32 | 33 | If you are not running helloSystem yet or would like to use the command line, the following command should work on all BSD flavors: 34 | 35 | ```console 36 | $ sudo dd if= of=/dev/daX bs=4m status=progress 37 | ``` 38 | 39 | On GNU-style systems (e.g., most Linux distributions), `status=progress` does not work and can be left away. 40 | 41 | ## Ventoy 42 | 43 | [Ventoy](https://github.com/ventoy/Ventoy/) is a tool that lets you boot the operating systems of multiple ISO files that are residing on the same disk, without the need to write the ISO to a physical device. Starting with version 1.0.62, Ventoy can boot helloSystem 0.7.0 and later. 44 | 45 | If you are not running helloSystem yet, then please refer to the Ventoy documentation on how to create a bootable Ventoy disk (that you put your ISOs on) using Windows or Linux. 46 | 47 | If you are already running helloSystem and would like to create a bootable Ventoy disk, please follow these steps instead since the Ventoy installation instructions since the Ventoy documentation only describes installation using Windows and Linux: 48 | 49 | ![image](https://user-images.githubusercontent.com/2480569/142038823-d7413735-73d9-44b4-84e5-c50768c2f271.png) 50 | 51 | 1. Run The __Create Live Media__ utility in helloSystem 52 | 2. From the drop-down menu, select __Ventoy__. Select the latest version (at least 1.0.62), and create a Ventoy Live medium (a 1 GB USB stick is sufficient for this) 53 | 3. Boot from the Ventoy Live medium you just created, and use it to install Ventoy to a disk (a SSD with hundreds of GB of space is recommended if you want to store hundreds of different operating system ISOs) 54 | 4. At this point, you don't need the Ventoy Live medium anymore (the 1 GB USB stick) 55 | 5. Put one or more helloSystem ISOs (and potentially ISOs of other operating systems supported by Ventoy) onto the Ventoy disk (the one with hundreds of GB of space) 56 | 6. Once a new version of Ventoy comes out, put the latest Ventoy Live ISO onto your Ventoy disk, just like any other operating system ISO. Boot it to update the Ventoy installation on the Ventoy disk itself (yes, it can update the disk it is running from) 57 | 58 | ## Tested hardware 59 | 60 | hello is known to boot to a graphical desktop on the following machines. Auxiliary functionality such as wireless networking, sound over HDMI, sleep, graphics acceleration, etc. has not yet been tested systematically. 61 | 62 | helloSystem developers currently have access to the following hardware: 63 | 64 | * [Framework Mainboard](https://frame.work/de/de/products/mainboard) (11th Gen Intel® Core™) 65 | * Acer TravelMate B117 66 | * Acer Revo RL85 67 | * Dell Inc. OptiPlex 780 68 | 69 | Please contact us if you would like to sponsor the project with a hardware donation. We are especially looking for Apple and Lenovo devices from the previous generations that should be available second-hand inexpensively. 70 | 71 | To see Hardware Probes of systems running helloSystem, please see the [helloSystem Hardware Database](http://bsd-hardware.info/?d=helloSystem&view=computers) provided by bsd-hardware.info. It is reasonable to assume that every system listed there can at least successfully boot helloSystem. Auxiliary functionality such as wireless networking, sound over HDMI, sleep, graphics acceleration, etc. may or may not be working. 72 | 73 | ### Networking hardware 74 | 75 | Not all networking devices may be supported by FreeBSD yet. In those cases, you may want to consider using a USB based networking devices. helloSystem developers currently have access to the following USB based networking devices which are known to work: 76 | 77 | * [USB 802.11n WLAN Adapters based on `ID 0bda:8176 Realtek Semiconductor Corp. RTL8188CUS`](https://vermaden.wordpress.com/2020/10/30/realtek-usb-wifi-review/) 78 | * [USB Wired Ethernet Adapters based on `ID 0b95:772b ASIX Electronics Corp. AX88772B`](https://www.freebsd.org/cgi/man.cgi?query=axe) 79 | 80 | Detailed information on #FreeBSD wireless network card compatibility is available at [https://wiki.freebsd.org/dev](https://wiki.freebsd.org/dev). 81 | 82 | ## Virtualization environments 83 | 84 | :::{note} 85 | We recommend running helloSystem on real hardware ("bare metal") if possible. This should give you the best possible performance and hardware support. 86 | ::: 87 | 88 | Users have reported success in running helloSystem in the following virtualization environments: 89 | 90 | * VirtualBox host (on FreeBSD and on macOS), known to work in BIOS and EFI modes 91 | * VMware Workstation works in BIOS and EFI modes (see below) 92 | * QEMU host (on Linux), works in both BIOS and EFI modes (see below). Note that for acceptable performance, QEMU needs KVM which is currently not available on FreeBSD hosts yet 93 | * Parallels host, reported to work in EFI mode (see below) 94 | * Proxmox VE 95 | 96 | Please note: 97 | 98 | * The VM needs to be __64-bit__ 99 | * The VM needs __at least 2 GB of RAM__ 100 | * The VM needs __at least 2 CPU cores__ 101 | * The boot process takes longer than you might expect; boot in verbose mode to see the details 102 | * For best results set **EFI/UEFI** boot mode (not BIOS) 103 | 104 | Please report back about the results on your virtualization environment. 105 | 106 | ### QEMU 107 | 108 | Create an 8 GiB (or larger) `hello.img` image file on which you can install the system: 109 | 110 | ```console 111 | $ pwd 112 | /home/user 113 | $ mkdir -p .qemu/hello 114 | $ fallocate -l $(( 8*1024*1024*1024 )) .qemu/hello/hello.img 115 | ``` 116 | 117 | Then, boot helloSystem: 118 | 119 | ```console 120 | $ qemu-system-x86_64 -machine type=q35,accel=kvm \ 121 | -enable-kvm -cpu host -smp 2 -m 4096 \ 122 | -device virtio-net,netdev=vmnic -netdev user,id=vmnic,hostfwd=tcp::5222-:22 \ 123 | -vga std -soundhw hda -no-quit \ 124 | -drive format=raw,file=${HOME}/.qemu/hello/hello.img \ 125 | -drive format=raw,file=${HOME}/Downloads/hello-0.4.0_0D26-FreeBSD-12.1-amd64.iso \ 126 | -boot menu=on 127 | ``` 128 | 129 | When QEMU starts, press `esc` and select `2` to boot the ISO. 130 | 131 | Use the __Install FreeBSD__ utility (System -> Applications -> Utilities -> Install FreeBSD) to install helloSystem to the disk image. 132 | 133 | Then restart QEMU, you now remove the last two options from the above command. 134 | 135 | Notes 136 | 137 | * The `hostfwd=` option creates a port forward from your host port `5222` to the Qemu VM port `22`. 138 | * Unfortunately the qemu-system-x86_64 USB tablet options do not work; you will need to press Ctrl+Alt+g to release the mouse pointer from the QEMU window 139 | * To make QEMU full screen, press Ctrl+Alt+F 140 | 141 | To boot/install hello in UEFI mode, first install [OVMF Open Virtual Machine Firmware](https://github.com/tianocore/tianocore.github.io/wiki/OVMF) on your host side. The package name for Fedora 32 is `edk2-ovmf` 142 | 143 | Then add these two `qemu-system-x86_64` options: 144 | 145 | ```text 146 | -bios /usr/share/edk2/ovmf/OVMF_CODE.fd \ 147 | -smbios type=0,vendor=0vendor,version=0version,date=0date,release=0.0,uefi=on \ 148 | ``` 149 | 150 | ### Parallels 151 | 152 | * Select Hardware > Boot Order. 153 | * Expand **Advanced Settings**. Set **BIOS** to "EFI 64-bit" and in the Boot flags field, enter `vm.bios.efi=1`. 154 | 155 | ![Screenshot](https://docs.01.org/clearlinux/latest/zh_CN/_images/parallels-07.png) 156 | 157 | ### Proxmox VE 158 | 159 | * Memory: 4GB (not ballooned) 160 | * Processors: 2 (1 socket 2 cores) 161 | * BIOS: OVMF (UEFI) 162 | * Display: Default (VGA) 163 | * Machine: q35 164 | * SATA Controller: VirtIO SATA for attaching virtual disk to (to install the system on) 165 | * CD Drive: helloSystem ISO 166 | * Hard Disk: At least 8GB Raw 167 | * Network Device: VirtIO 168 | 169 | To set resolution, press F2 at boot to access OVMF settings. Select 'Device Manager > OVMF Platform Configuration > Change Preferred', save and reboot. 170 | 171 | ### VMware Workstation 172 | Tested on VMware Workstation 16.2.1 173 | 174 | :::{admonition} Installation issue 175 | :class: warning 176 | 177 | For best results while installing, please set your CPU to 1 socket, and no more than 4 cores 178 | 179 | After installation, you can set the CPU socket and core count to your desire. 180 | ::: 181 | 182 | * Memory: 4GB 183 | * Processors: 4 (1 socket, 4 cores) 184 | * Hard Disk: At least 8GB 185 | * Guest Operating System Version: FreeBSD 12 64-bit 186 | -------------------------------------------------------------------------------- /user/troubleshooting.md: -------------------------------------------------------------------------------- 1 | # Troubleshooting 2 | 3 | ## Notable issues 4 | 5 | ### FreeBSD logo on screen for more than five minutes 6 | 7 | It can take up to five minutes to start the system in Live mode. If you see the FreeBSD logo on screen for more than five minutes, then something might be wrong and you might need to restart the computer. 8 | 9 | If – after five minutes – you're reluctant to stop the computer, you can occasionally [key {kbd}`Ctrl-T`](https://hellosystem.github.io/docs/developer/boot.html#seeing-what-the-system-is-doing-while-the-graphical-boot-screen-is-shown) to get some information about what the computer is doing. If there is no change from one snippet to the next, across three or more snippets, you may reasonably assume that the computer needs to be restarted. 10 | 11 | * Please restart the computer. If normal use of the power button is not effective, press and hold. 12 | * Then, please [start the computer in verbose mode](https://hellosystem.github.io/docs/developer/boot.html#boot-in-verbose-mode) to see any relevant error messages that may help in resolving the issue. 13 | 14 | ### Boot stalls with black screen 15 | 16 | This means that Xorg has been started but for some reason the login manager `slim` or the helloDesktop startup script `start-hello` cannot run. 17 | 18 | * Boot in verbose mode 19 | * Press {kbd}`Ctrl+Alt+F2` 20 | * Log in 21 | * `sudo killall Xorg` 22 | * `sudo service dbus restart` 23 | * `sudo service slim restart` 24 | 25 | If this does not work: 26 | 27 | * `sudo killall Xorg` 28 | * `startx` 29 | * In XTerm, `sudo liveuser` (or the username you chose) 30 | * `start-hello` 31 | 32 | ### `login:` prompt, no desktop environment 33 | 34 | * Please make sure that your computer has at least 4GB of RAM. helloSystem currently needs at least this amount to be started in Live mode. 35 | * The graphics hardware in your computer may not yet, or not yet easily, be usable with helloSystem. Try with a different computer, or seek help. 36 | 37 | ## Debugging application issues 38 | 39 | When debugging application issues, it can be helpful to see what an application is actually doing. For example, if we are interested in which libraries with "menu" in their name `firefox` is loading, we can run 40 | 41 | ```console 42 | $ LD_DEBUG=libs firefox 2>&1 | grep -i menu 43 | ``` 44 | 45 | Or, if we are interested in which activities with "menu" in their name `firefox` is doing, we can run 46 | 47 | ```console 48 | $ sudo sysctl security.bsd.unprivileged_proc_debug=1 49 | $ truss firefox 2>&1 | grep -e menu 50 | ``` 51 | 52 | ## Other issues 53 | 54 | Use the *Search or jump to…* field at the head of the main [https://github.com/helloSystem/](https://github.com/helloSystem/) page – above the helloSystem logo. This special page allows an organisation-wide search, across all helloSystem repositories. Click in the field, then begin typing. 55 | 56 | If your issue is not already reported, you can create a new one. 57 | 58 | ## Getting help 59 | 60 | Please participate in our [discussion forum](https://github.com/helloSystem/hello/discussions) or [contact us](https://hellosystem.github.io/docs/developer/contact.html). 61 | --------------------------------------------------------------------------------