diff --git a/buildDocs.sh b/buildDocs.sh index 9fb0f494..b5523f84 100644 --- a/buildDocs.sh +++ b/buildDocs.sh @@ -20,8 +20,7 @@ set -x apt-get update apt-get -y install git rsync python3-pip # qttools5-dev-tools qt5-default qt5-qmake pip3 install setuptools wheel -pip3 install docutils==0.16 sphinx sphinx-autobuild sphinx-rtd-theme commonmark recommonmark sphinx-markdown-tables markdown!=3.3.5 # sphinxcontrib-qthelp -# markdown!=3.3.5 = Workaround for ryanfox/sphinx-markdown-tables#34 +pip3 install docutils==0.16 sphinx>=5.0.0 sphinx-autobuild sphinx_rtd_theme>=0.5.2 myst-parser # sphinxcontrib-qthelp ##################### # DECLARE VARIABLES # diff --git a/conf.py b/conf.py index 0e4843b2..8572031d 100644 --- a/conf.py +++ b/conf.py @@ -16,9 +16,6 @@ # import sys # sys.path.insert(0, os.path.abspath('.')) -import recommonmark -from recommonmark.transform import AutoStructify - # -- Project information ----------------------------------------------------- @@ -38,10 +35,13 @@ extensions = [ # Auto-generate section labels. 'sphinx.ext.autosectionlabel', - 'recommonmark', - 'sphinx_markdown_tables' + 'myst_parser' ] +# Enable code fences to be written with colons for extra control + +myst_enable_extensions = ["colon_fence"] + master_doc = 'index' # Prefix document path to section labels, otherwise autogenerated labels would look like 'heading' @@ -95,17 +95,3 @@ ] github_doc_root = 'https://' + GITHUB_REPO_OWNER + '.github.io/' + GITHUB_REPO_NAME + '/' - - -def setup(app): - app.add_config_value( - 'recommonmark_config', - { - 'enable_auto_toc_tree': False, - 'url_resolver': lambda url: github_doc_root + url, - 'auto_toc_tree_section': 'Contents', - }, - True - ) - - app.add_transform(AutoStructify) diff --git a/developer/application-bundles.md b/developer/application-bundles.md index cbb3b173..975c241b 100644 --- a/developer/application-bundles.md +++ b/developer/application-bundles.md @@ -23,7 +23,7 @@ helloSystem supports simplified GNUstep-style `.app` bundles. Minimal requirements: -``` +```text ./Application.app ./Application.app/Application <-- (link to) the executable to be launched when Application.app is double clicked ./Application.app/Resources/Application.png <-- the application icon (png format) @@ -38,7 +38,7 @@ helloSystem supports simplified ROX-style `.AppDir` bundles. Minimal requirements: -``` +```text ./Application.AppDir ./Application.AppDir/AppRun <-- (link to) the executable to be launched when Application.app is double clicked ./Application.AppDir/.DirIcon <-- the application icon (png format) @@ -70,10 +70,10 @@ Please see the [`.cirrus.yml`](https://github.com/helloSystem/QHexEdit/blob/main If an application is supposed to load privately bundled libraries, one must patch it so that it loads privately bundled libraries from a path relative to itself (`$ORIGIN`) rather than from `/usr/local/lib`: -``` -sed -i -e 's|/usr/local/lib|$ORIGIN/../lib|g' usr/local/bin/falkon -ln -s usr/local/lib . -rm usr/local/bin/falkon-e +```console +$ sed -i -e 's|/usr/local/lib|$ORIGIN/../lib|g' usr/local/bin/falkon +$ ln -s usr/local/lib . +$ rm usr/local/bin/falkon-e ``` This works because by coincidence the string `/usr/local/lib` has the exact same length as `$ORIGIN/../lib`. If this was not the case, one would need to either specify the rpath at compilation time, or use a tool such as `patchelf`. diff --git a/developer/applications.md b/developer/applications.md index 3af10fe5..02193675 100644 --- a/developer/applications.md +++ b/developer/applications.md @@ -19,7 +19,7 @@ For an introduction to [Creating GUI applications with Python & Qt5](https://www Using Qt Creator, you can also create and edit graphical user interfaces for __Python__ based applications using `.ui` files. These can be used in PyQt like this: -``` +```py #!/usr/bin/env python3 # This Python file uses the following encoding: utf-8 diff --git a/developer/architecture.md b/developer/architecture.md index 8a6de876..336728db 100644 --- a/developer/architecture.md +++ b/developer/architecture.md @@ -32,14 +32,14 @@ A Dock that shows icons for running and pinned applications. (In the future it s ### `launch` command -The `launch` command is used to launch applications without specifying a path to them. +The {command}`launch` command is used to launch applications without specifying a path to them. -The `launch` command is expected to determine the preferred instance of an application with the given name. (The `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 `launch` command should also gain knowledge of which application to open a file with. +The {command}`launch` command is expected to determine the preferred instance of an application with the given name. (The {command}`launch` command is supposed to find the _preferred_ instance, e.g., the one with the highest version, the one last put onto the system, etc.) Eventually the {command}`launch` command should also gain knowledge of which application to open a file with. -Filer is supposed to launch all applications through the `launch` command. Shell scripts, `.desktop` files, etc. should be written to use the `launch` command rather than hardcoding paths to applications, where appropriate. +Filer is supposed to launch all applications through the {command}`launch` command. Shell scripts, `.desktop` files, etc. should be written to use the {command}`launch` command rather than hardcoding paths to applications, where appropriate. -If an application cannot be launched, the `launch` command shall give a localized, understandable clear-text error message and offer a solution if possible; fall back to the console output of the application that could not be launched. -When beginning to launch an application, the `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). +If an application cannot be launched, the {command}`launch` command shall give a localized, understandable clear-text error message and offer a solution if possible; fall back to the console output of the application that could not be launched. +When beginning to launch an application, the {command}`launch` command shall notify the Dock via some IPC mechanism (ideally something _much_ simpler than the convoluted D-Bus) about the icon and name of the application about to be launched, so that the Dock can start a launch animation until the application is showing its first window). ### IPC mechanism for the desktop @@ -47,7 +47,7 @@ A very simple IPC mechanism should be introduced for the desktop components to t ### Applications -Applications must not need to be installed. Simply downloading them, attaching an external drive containing them, or connecting to a network share containing them must be sufficient. Multiple versions of the same application must be able to co-exist. The `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. +Applications must not need to be installed. Simply downloading them, attaching an external drive containing them, or connecting to a network share containing them must be sufficient. Multiple versions of the same application must be able to co-exist. The {command}`launch` command is responsible to determine which one to use in cases where the user did not explicitly launch a specific instance by double-clicking it. Custom-written applications should come as Application bundles whenever possible. It is acceptable for pre-existing applications to come with legacy XDG desktop files instead. diff --git a/developer/base.md b/developer/base.md index e2e8b8b2..1cf1d302 100644 --- a/developer/base.md +++ b/developer/base.md @@ -1,6 +1,7 @@ # Working with the FreeBSD base system In some situations it may be necessary to make changes to existing software that comes in the FreeBSD base system. + This section describes how to make such changes using an example. ## Example @@ -9,41 +10,41 @@ Suppose you would like to make a small change to the source code of software tha Here is a real-life example on how to do that: -https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=251025 can be fixed by changing a few lines in + can be fixed by changing a few lines in -https://github.com/freebsd/freebsd-src/blob/main/usr.sbin/efivar/efivar.c + ## Installing the FreeBSD source code 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. -From http://ftp.freebsd.org/pub/FreeBSD/releases/amd64/12.2-RELEASE/ (or from whatever FreeBSD version you are using) download `src.txz`. Then: +From (or from whatever FreeBSD version you are using) download {file}`src.txz`. Then: -``` -cd / -sudo tar xf ~/Downloads/src.txz -rm ~/Downloads/src.txz +```console +$ cd / +$ tar xf ~/Downloads/src.txz +$ rm ~/Downloads/src.txz ``` ## Building a command line tool without changes Build the command line tool without changes first to ensure it builds and works as expected. -``` -cd /usr/src/usr.sbin/efivar/ -make -/usr/obj/usr/src/amd64.amd64/usr.sbin/efivar/efivar +```console +$ cd /usr/src/usr.sbin/efivar/ +$ make +$ /usr/obj/usr/src/amd64.amd64/usr.sbin/efivar/efivar ``` ## Making changes Now make changes to the command line tool. -``` -cd /usr/src/usr.sbin/efivar/ -rm efivar.c -# From https://reviews.freebsd.org/D29620 -wget "https://reviews.freebsd.org/file/data/yytb47lr5cxaijaaupeh/PHID-FILE-gihl33z7feu4dagjxjgz/usr.sbin_efivar_efivar.c" -O efivar.c -make -/usr/obj/usr/src/amd64.amd64/usr.sbin/efivar/efivar +```console +$ cd /usr/src/usr.sbin/efivar/ +$ rm efivar.c +// From https://reviews.freebsd.org/D29620 +$ wget "https://reviews.freebsd.org/file/data/yytb47lr5cxaijaaupeh/PHID-FILE-gihl33z7feu4dagjxjgz/usr.sbin_efivar_efivar.c" -O efivar.c +$ make +$ /usr/obj/usr/src/amd64.amd64/usr.sbin/efivar/efivar ``` diff --git a/developer/binary-compatibility.md b/developer/binary-compatibility.md index 494d032a..82d0fc58 100644 --- a/developer/binary-compatibility.md +++ b/developer/binary-compatibility.md @@ -2,16 +2,16 @@ 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." -``` .. note:: - This page is in draft status and needs to be reviewed by experienced FreeBSD developers. Pull requests welcome. -``` +:::{note} +This page is in draft status and needs to be reviewed by experienced FreeBSD developers. Pull requests welcome. +::: - ## Application compatibility - - 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`). - - * 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 - * 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. +## Application compatibility + +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`). + +* 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 +* 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. ### Recommendation for building binary compatible applications @@ -20,29 +20,28 @@ Build on the `.0` minor version for each still-supported major version of FreeBS This should allow the application to run on all still-supported FreeBSD releases. - ## Kernel module compatibility - - The Kernel Binary Interface (KBI) defines which kernel extensions can run on which systems. +## Kernel module compatibility + +The Kernel Binary Interface (KBI) defines which kernel extensions can run on which systems. -``` .. note:: - Section to be written. Pull requests welcome. -``` +:::{note} +Section to be written. Pull requests welcome. +::: - * 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. - - __Note:__ The `i915kms` package that contains the Intel GPU driver breaks on 12.2-RELEASE. - -``` .. note:: - Explanation to be written. Pull requests welcome. -``` - +* 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. + +__Note:__ The `i915kms` package that contains the Intel GPU driver breaks on 12.2-RELEASE. +:::{note} +Explanation to be written. Pull requests welcome. +::: + ### Recommendation for building binary compatible kernel modules 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. - ## References - - * https://wiki.freebsd.org/BinaryCompatibility describes best practices for maintaining binary compatibility in FreeBSD - * [i915kms package breaks on 12.2-RELEASE](https://forums.freebsd.org/threads/i915kms-package-breaks-on-12-2-release-workaround-build-from-ports.77501/) +## References + +* describes best practices for maintaining binary compatibility in FreeBSD +* [i915kms package breaks on 12.2-RELEASE](https://forums.freebsd.org/threads/i915kms-package-breaks-on-12-2-release-workaround-build-from-ports.77501/) diff --git a/developer/boot.md b/developer/boot.md index 8ea96f47..7382acb7 100644 --- a/developer/boot.md +++ b/developer/boot.md @@ -4,26 +4,27 @@ 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. -While it would be possible to change the order of the scripts in `/etc/rc.d` and `/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. +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. 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. -``` .. note:: - 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. -``` +:::{note} +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. +::: To do this, create a Boot Environment that you can roll back to in case things go wrong. -In `/etc/rc.conf`, set -``` +In {file}`/etc/rc.conf`, set + +```text defaultroute_carrier_delay="0" defaultroute_delay="0" background_dhclient="YES" ``` -Then create the following `/usr/local/etc/rc.d/late-start` script: +Then create the following {file}`/usr/local/etc/rc.d/late-start` script: -``` +```sh #!/bin/sh # PROVIDE: late-start @@ -62,20 +63,19 @@ late_disable_early_services() load_rc_config $name run_rc_command "$1" - ``` Disable the services in question with -``` -sudo chmod +x /usr/local/etc/rc.d/late-start -sudo service late-start disable_early_services +```console +$ sudo chmod +x /usr/local/etc/rc.d/late-start +$ sudo service late-start disable_early_services ``` Check which services are still enabled, should now be treatly reduced: -``` -% grep -r 'enable="YES"' /etc/rc.conf* +```console +$ grep -r 'enable="YES"' /etc/rc.conf* /etc/rc.conf:clear_tmp_enable="YES" /etc/rc.conf:dbus_enable="YES" /etc/rc.conf:initgfx_enable="YES" @@ -96,8 +96,8 @@ Press the Backspace key on your keyboard during early boot until you see the `OK Enter -``` -boot -s +```console +OK boot -s ``` to boot in single user mode. The system will boot to the first stage Live system prompt: @@ -105,32 +105,32 @@ to boot in single user mode. The system will boot to the first stage Live system ![livefirstsingleprompt](https://user-images.githubusercontent.com/2480569/202910574-22c0e284-8717-4ae0-9489-68cc23995e1d.png) At this point, the Live system has not been made writable yet. -Enter `exit` to contine. The system will boot to the second stage Live system prompt: +Enter {command}`exit` to contine. The system will boot to the second stage Live system prompt: ![livesecondsingleprompt](https://user-images.githubusercontent.com/2480569/202910576-e4253133-8544-4566-8b8e-8c0895f63edd.png) -At this point, the system has been made partly writable by the `init_script`. To see the messages, you can press the ScrLk key on your keyboard and then use the arrow up and arrow down keys on your keyboard. Then press the ScrLk key again. +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. -Hit the Enter key on your keyboard. +Hit the {kbd}`Enter` key on your keyboard. -Here you can make changes to files like `/usr/local/bin/start-hello`. +Here you can make changes to files like {file}`/usr/local/bin/start-hello`. For example, you can -``` -mv /usr/local/bin/start-hello /usr/local/bin/start-hello.original -ln -sf /usr/local/bin/xterm /usr/local/bin/start-hello +```console +$ mv /usr/local/bin/start-hello /usr/local/bin/start-hello.original +$ ln -sf /usr/local/bin/xterm /usr/local/bin/start-hello ``` -Then enter `exit` to contine. The system will boot into the graphical desktop. +Then enter {command}`exit` to contine. The system will boot into the graphical desktop. If you have made the above changes, you can run -``` -sh -x /usr/local/bin/start-hello.original +```console +$ sh -x /usr/local/bin/start-hello.original ``` -to watch `start-hello.original` run in a graphical terminal. +to watch {file}`start-hello.original` run in a graphical terminal. ![image](https://user-images.githubusercontent.com/2480569/202913068-5399a4fa-cefc-4ffc-ba24-9b752d6a4cff.png) @@ -138,9 +138,9 @@ Here you can see what goes wrong, if anything... and then you can create, e.g., ## Live system early boot process -``` .. note:: - 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. -``` +:::{note} +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. +::: 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. @@ -149,17 +149,17 @@ FreeBSD does not have a standard way to achieve this, so custom code has to be u This is a simplified description of the boot process. There may be additional aspects which still need to be documented. 1. The bootloader gets loaded -1. The bootloader loads the kernel modules that are required for the Live system boot process as specified in `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` -1. The bootloader loads the ramdisk image `ramdisk.ufs` as specified in `overlays/boot/boot/loader.conf` under `mfsroot_name`. The contents of the ramdisk image are specified in `overlays/ramdisk` -1. `init.sh` from the ramdisk image gets executed as requested by `overlays/boot/boot/loader.conf` under `init_script` and specified in `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` -1. `/usr/local/bin/furybsd-init-helper` gets executed by `init.sh` in a chroot of the live filesystem, `/livecd`. It is defined in `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 -1. The `/livecd` chroot is exited -1. `init.sh` from the ramdisk image exits -1. `etc/rc` from the ramdisk image gets executed as specified in `overlays/ramdisk/etc/rc` (by what?). It tells the kernel to "reroot" (not "chroot") into the live filesystem, `/livecd` using `reboot -r` -1. From here on, the boot process is the regular FreeBSD boot process with the following particularities: -1. `/etc/rc.d/initgfx` detects the GPU and loads the appropriate drivers -3. `/usr/local/etc/rc.d/localize` runs `/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 -4. The `slim` session manager (login window) is started; when the user is logged in, it starts the script `/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 +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` +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` +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` +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 +6. The `/livecd` chroot is exited +7. `init.sh` from the ramdisk image exits +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` +9. From here on, the boot process is the regular FreeBSD boot process with the following particularities: +10. {file}`/etc/rc.d/initgfx` detects the GPU and loads the appropriate drivers +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 +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 ### Troubleshooting the Live system early boot process @@ -189,9 +189,9 @@ Example: `load: 0.62 cmd: sleep 1739 [nanslp] 2.97r 0.00u 0.00s 0% 2168k` 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. -1. While the bootloader is running, keep the __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 __Esc__ key on your keyboard immediately when you see this) -1. Type `unset boot_mute` and press the __Enter__ key. This disables the graphical splash screen and results in boot messages being shown -1. Type `boot -v` and press the __Enter__ key. This results in the system being booted in verbose mode +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) +2. Type `unset boot_mute` and press the {kbd}`Enter` key. This disables the graphical splash screen and results in boot messages being shown +3. Type `boot -v` and press the {kbd}`Enter` key. This results in the system being booted in verbose mode The computer should boot into a graphical desktop. @@ -199,27 +199,27 @@ The computer should boot into a graphical desktop. 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. -1. While the bootloader is running, keep the __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 __Esc__ key on your keyboard immediately when you see this) -1. Type `unset boot_mute` and press the __Enter__ key. This disables the graphical splash screen and results in boot messages being shown -1. Type `boot -v -s` and press the __Enter__ key. This results in the system being booted in verbose single-user mode +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) +1. Type `unset boot_mute` and press the {kbd}`Enter` key. This disables the graphical splash screen and results in boot messages being shown +1. Type `boot -v -s` and press the {kbd}`Enter` key. This results in the system being booted in verbose single-user mode The computer should boot into a text console rescue system in which parts of `init.sh` from the ramdisk image have run. -``` .. note:: - Single-user mode on the Live system currently is for developers of the Live system only. - - 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. -``` +:::{note} +Single-user mode on the Live system currently is for developers of the Live system only. + +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. +::: ## Graphical desktop start process -1. The system is configured in `/etc/rc.conf` to start the `slim` login manager. This also results in Xorg being started -1. `slim` is configured in `/usr/local/etc/slim.conf` to start `start-hello` once the user has logged in, or if autologin has occurred -1. The `/usr/local/bin/start-hello` shell script starts the various components of the helloSystem desktop +1. The system is configured in {file}`/etc/rc.conf` to start the `slim` login manager. This also results in Xorg being started +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 +3. The {file}`/usr/local/bin/start-hello` shell script starts the various components of the helloSystem desktop ### Troubleshooting the graphical desktop start process -* Login manager (`slim`) says __Failed to execute login command__. Check the `/usr/local/bin/start-hello` shell script. +* Login manager (`slim`) says __Failed to execute login command__. Check the {file}`/usr/local/bin/start-hello` shell script. ## Installed system boot process @@ -227,7 +227,7 @@ The boot process is the regular FreeBSD boot process. Please refer to [The FreeB ## Boot Mute -Setting `boot_mute="YES"` in `/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. +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. Since helloSystem targets a broad audience including non-technical users, the following behavior is intended: * By default, show no textual boot messages @@ -237,15 +237,15 @@ Since helloSystem targets a broad audience including non-technical users, the fo To achieve this, helloSystem uses a combination of the following techniques: * Read the `boot_mute` kernel environment variable and adjust the userland boot process accordingly -* Modify `/etc/rc` to run `conscontrol delete ttyv0` and redirect all of its output to `/dev/null` if `boot_mute` is set to `YES` -* Modify `/etc/rc.shutdown` to redirect all of its output to `/dev/null` if `boot_mute` is set to `YES` +* 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` +* Modify {file}`/etc/rc.shutdown` to redirect all of its output to `/dev/null` if `boot_mute` is set to `YES` * 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 -* Replace the `/etc/ttys` file with an empty file to not spawn login shells on the text-mode console -* Commenting out the line that ends in `/dev/console` in `/etc/syslog.conf` to prevent boot from being visually interrupted by `syslog` messages +* Replace the {file}`/etc/ttys` file with an empty file to not spawn login shells on the text-mode console +* Commenting out the line that ends in `/dev/console` in {file}`/etc/syslog.conf` to prevent boot from being visually interrupted by `syslog` messages * 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` -``` .. note:: - 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. -``` +:::{note} +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. +::: -To see boot messages, set `boot_mute="NO"` in `/boot/loader.conf` or at the bootloader prompt. +To see boot messages, set `boot_mute="NO"` in {file}`/boot/loader.conf` or at the bootloader prompt. diff --git a/developer/building.md b/developer/building.md index 3719e65b..eb57c90e 100644 --- a/developer/building.md +++ b/developer/building.md @@ -21,28 +21,28 @@ However, it is also possible to build the ISO locally, which is especially handy ## Building the Live ISO -``` -sudo pkg install -y pkg git-lite zsync wget sha bash zip devel/py-xdg librsvg2 ca_root_nss -git clone https://github.com/helloSystem/ISO -cd ISO -sudo ./build.sh hello +```console +$ sudo pkg install -y pkg git-lite zsync wget sha bash zip devel/py-xdg librsvg2 ca_root_nss +$ git clone https://github.com/helloSystem/ISO +$ cd ISO +$ sudo ./build.sh hello ``` -The resulting Live ISO will be located at `/usr/local/furybsd/iso/`. +The resulting Live ISO will be located at {file}`/usr/local/furybsd/iso/`. ## Writing Live Media to USB drive -``` -sudo dd if=/usr/local/furybsd/iso/FuryBSD-12.1-XFCE.iso of=/dev/daX bs=4m status=progress +```console +$ sudo dd if=/usr/local/furybsd/iso/FuryBSD-12.1-XFCE.iso of=/dev/daX bs=4m status=progress ``` Replace `daX` with the respective device name. -``` .. warning:: - This will overwrite the entire contents of the selected device. Take extra caution when determining the device name. - - This operation cannot be undone. -``` +:::{warning} +This will overwrite the entire contents of the selected device. Take extra caution when determining the device name. + +This operation cannot be undone. +::: For end users, there is the __Create Live Media__ application that can conveniently download and write Live Media with a graphical user interface. @@ -50,9 +50,9 @@ For end users, there is the __Create Live Media__ application that can convenien You can use the `cdrecord` command line tool to burn Live Media to DVD. -``` -pkg install cdrtools -cdrecord /usr/local/furybsd/iso/.iso +```console +# pkg install cdrtools +# cdrecord /usr/local/furybsd/iso/.iso ``` ## Customizing the Live ISO @@ -83,10 +83,10 @@ Configuration is applied using _transient packages_ that get generated on-the-fl * Overlays for the initial ramdisk are stored in `overlays/ramdisk` * 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. -For example, a file that is supposed to appear in `/usr/local/bin/app` on the main filesystem could be stored in `overlays/uzip/hello/files/usr/local/bin/app`. +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`. ### Customizing the build script -If a file called `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, `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. +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. All desktop-specific build steps should go into this file. diff --git a/developer/developer-tools.md b/developer/developer-tools.md index cce398e9..bb8ef78d 100644 --- a/developer/developer-tools.md +++ b/developer/developer-tools.md @@ -4,18 +4,9 @@ Starting with helloSystem 0.7.0, compilers, headers, `.o` files and other files The __Developer__ folder in the __Applications__ folder contains useful development tools for use with helloSystem. -* __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 -* __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 -* __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 -* __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. +* __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 +* __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 +* __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 +* __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. -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. +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. diff --git a/developer/distributions.md b/developer/distributions.md index e7142136..9bf58ce6 100644 --- a/developer/distributions.md +++ b/developer/distributions.md @@ -10,6 +10,6 @@ __Please do not call your derivatives "hello" or "helloSystem"__. In order to ke You may want to include the desktop components of helloSystem, the **helloDesktop** "Desktop Environment" (collection of individual components, really). -For example, work is being done to bring the helloDesktop components to FreeBSD: https://wiki.freebsd.org/helloDesktop. But please note that "FreeBSD with helloDesktop" is not the same as helloSystem. +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. Please do not hesitate to contact the team if you have questions regarding this policy. diff --git a/developer/filer-context-menus.md b/developer/filer-context-menus.md index 63a102fa..876fedf3 100644 --- a/developer/filer-context-menus.md +++ b/developer/filer-context-menus.md @@ -2,15 +2,15 @@ It is possible to extend Filer context menu items by writing files that conform to the __DES-EMA__ (Desktop Entry Specification - Extension for Menus and Actions). Apparently this format was never adopted as a standard, so it is documented here. The information on this page is based on [draft 0.15](https://gitlab.gnome.org/GNOME/filemanager-actions/-/blob/NAUTILUS_ACTIONS_3_2_4/docs/des-ema/des-ema-0.15) from November 23, 2010. -``` .. note:: - Filer inherits its DES-EMA implementation from PCManFM, but may use a different format in the future. - - It still needs to be verified which portions have actually been implemented in Filer, so currently this page describes functionality which may or may not be implemented in Filer. Corrections are welcome. -``` +:::{note} +Filer inherits its DES-EMA implementation from PCManFM, but may use a different format in the future. + +It still needs to be verified which portions have actually been implemented in Filer, so currently this page describes functionality which may or may not be implemented in Filer. Corrections are welcome. +::: Changes take effect after a restart of Filer. To restart Filer: -1. Press Ctrl+Alt+Esc and click on the Desktop to force-quit it -2. Press Alt+F2 and enter `launch Filer --desktop` to start it again +1. Press {kbd}`Ctrl+Alt+Esc` and click on the Desktop to force-quit it +2. Press {kbd}`Alt+F2` and enter `launch Filer --desktop` to start it again ## Examples @@ -18,7 +18,7 @@ Changes take effect after a restart of Filer. To restart Filer: In the following example, we define an "Open terminal here" action, which has three profiles. These profiles are thought to be able to open a suitable terminal in most situations. They are ordered, and so only the first profile whose conditions are met at runtime will be used in the Filer context menu. -``` +```text [Desktop Entry] Name=Open terminal here Tooltip=Open a new terminal here @@ -43,7 +43,7 @@ Schemes=x-nautilus-desktop; Exec=launch QTerminal --workdir ~/Desktop ``` -This may be saved, e.g. as `~/.local/share/file-manager/actions/open-terminal.desktop` file. +This may be saved, e.g. as {file}`~/.local/share/file-manager/actions/open-terminal.desktop` file. Note that this is only an example of how an action may be defined in a `.desktop` file. It has not been deeply tested, and there is most probably more efficient ways of opening a terminal somewhere... @@ -51,7 +51,7 @@ Note that this is only an example of how an action may be defined in a `.desktop Suppose we would like to place the menu elements into a submenu. To achieve this, we create a second `.desktop` file with following content: -``` +```text [Desktop Entry] Type=Menu Name=Terminal menu @@ -60,7 +60,7 @@ Icon=terminal-group ItemsList=open-terminal; ``` -This may be saved, e.g. as `~/.local/share/file-manager/actions/menu-terminal.desktop` file. +This may be saved, e.g. as {file}`~/.local/share/file-manager/actions/menu-terminal.desktop` file. ## Desktop file @@ -68,11 +68,11 @@ This may be saved, e.g. as `~/.local/share/file-manager/actions/menu-terminal.de This specification relies on the common syntax defined in the [Desktop Entry Specification](http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html). Here is a summary of some main points: -* Files are UTF-8 encoded. -* All keys and values are case sensitive. -* The `[Desktop Entry]` group must be the first group of the file. -* Boolean values must be `true` or `false`. -* Strings, in strings lists, are semicolon-separated; the list itself ends with a semicolon. +* Files are UTF-8 encoded. +* All keys and values are case sensitive. +* The `[Desktop Entry]` group must be the first group of the file. +* Boolean values must be `true` or `false`. +* Strings, in strings lists, are semicolon-separated; the list itself ends with a semicolon. #### Desktop file identifier @@ -80,7 +80,7 @@ In the rest of this specification, when a desktop file needs to be identified, w #### Desktop files search path -`.desktop` files are searched for in `XDG_DATA_DIRS/file-manager/actions` directories. All used _desktop_file_id_s should be unique. +`.desktop` files are searched for in {file}`XDG_DATA_DIRS/file-manager/actions` directories. All used _desktop_file_id_s should be unique. ## Managed objects @@ -317,19 +317,20 @@ Defaults to `Name` value. The ordered list of the profiles attached to this action. Each element of this strings list may be: -* a _profile_id_, _i.e._ the id of a profile, as an ASCII string -* a command to be executed, if the string is enclosed between square brackets (`[`...`]`). +* a `_profile_id_`, _i.e._ the id of a profile, as an ASCII string +* a command to be executed, if the string is enclosed between square brackets (`[`...`]`). So, `Profiles` key has a dynamic value: if an element of the string list is enclosed between square brackets (`[`...`]`), it is considered as a command, optionally with After reading, and maybe evaluation of dynamic elements, profiles identified by the `Profiles` value, but not found in this `.desktop` file, are just ignored. It is up to the implementation to decide whether profiles found in this `.desktop` file, but not identified in this list, should or not be attached to the action. -It could be for example an acceptable fallback to append these "orphan" profiles at the end of the list of profiles. +It could be for example an acceptable fallback to append these "orphan" profiles at the end of the list of profiles. + Another choice might also be: -* at runtime, only attach to the action profiles which are listed in this `Profiles` key -* while a management UI may load all profiles found in the `.desktop` file. +* at runtime, only attach to the action profiles which are listed in this `Profiles` key +* while a management UI may load all profiles found in the `.desktop` file. @@ -491,7 +492,7 @@ It is the responsibility of the implementation to ensure that the displayed menu As stated -The menu is so defined as a particular case of a `.desktop` file, identified by its _desktop_file_id_, whose the `[Desktop Entry]` section has following keys: +The menu is so defined as a particular case of a `.desktop` file, identified by its `desktop_file_id`, whose the `[Desktop Entry]` section has following keys: @@ -997,16 +998,16 @@ Actually, the command defined in the `Exec` key will be executed once, or repeat Though some parameters are not sensible to the count of the selection (e.g. `%c`, the selection count itself), most have two declensions: -* a "singular" one, e.g. `%b`, the basename of the selected item -* a "plural" one, e.g. `%B`, a space-separated list of the basenames of selected items +* a "singular" one, e.g. `%b`, the basename of the selected item +* a "plural" one, e.g. `%B`, a space-separated list of the basenames of selected items When the selection is empty or contains only one element, and from this topic point of view, these two forms are exactly equivalent. When the selection contains more than one item: -* if the first relevant parameter found in the `Exec` key is of a singular form, then the implementation should consider that the command is only able to deal with one item at a time, and thus that it has to be ran one time for each selected item; -* contrarily, if the first relevant parameter found is of the plural form, then the implementation should consider that the command is able to deal with a list of items, and thus the command should be executed only once; -* if all found parameters are "irrelevant", then the default is to consider that the command should be executed only once. +* if the first relevant parameter found in the `Exec` key is of a singular form, then the implementation should consider that the command is only able to deal with one item at a time, and thus that it has to be ran one time for each selected item; +* contrarily, if the first relevant parameter found is of the plural form, then the implementation should consider that the command is able to deal with a list of items, and thus the command should be executed only once; +* if all found parameters are "irrelevant", then the default is to consider that the command should be executed only once. Example: @@ -1379,27 +1380,25 @@ The processus described here is only a sort of meta-algorithm, whose only goal i The implementer might take advantage of preparing once the whole hierarchy of the menus and actions: -* to minimize the time spent in the parsing of all files; -* to identify and eliminate duplicate _desktop_file_id_s, -* to eliminate invalid menus and actions. - -1. as described in desktop_file_ids and invalid `.desktop` files; implementation so obtains a flat list of menus or actions; +* to minimize the time spent in the parsing of all files; +* to identify and eliminate duplicate _desktop_file_id_s, +* to eliminate invalid menus and actions. +1. as described in desktop_file_ids and invalid `.desktop` files; implementation so obtains a flat list of menus or actions; 2. recursively build the hierarchy; this merely consists in the build of the hierarchy as a tree of menus and actions, where each _desktop_file_id_ addressed as the subitem of a menu consumes this same id from the flat list - * if the level-zero order (which is not specified here, but see desktop_file_id addressed in the level zero consumes this same id from the flat list; - * else, if might be reasonable to start with an empty tree; - + * if the level-zero order (which is not specified here, but see desktop_file_id addressed in the level zero consumes this same id from the flat list; + * else, if might be reasonable to start with an empty tree; 3. at the end, implementation stays with: - * the output tree with some menus at the root; - * some actions, left in the input flat list because they were not addressed by any menu; these left actions should be added to the level zero of the hierarchy (though in a unspecified order) - * some menus, left in the input flat list because their subitems were not found; as these menus happen to be empty, they must be considered as invalid. + * the output tree with some menus at the root; + * some actions, left in the input flat list because they were not addressed by any menu; these left actions should be added to the level zero of the hierarchy (though in a unspecified order) + * some menus, left in the input flat list because their subitems were not found; as these menus happen to be empty, they must be considered as invalid. After this built phase, the resultant tree only contains valid (before runtime parameters expansion) menus and actions. So, menus or actions may appear at the level zero of the whole hierarchy for only two reasons: -1. because they are explicitly addressed by the level-zero configuration, if the implementation defines it; this may concern menus and actions; -2. because these items were not addressed by any menu (but this may only concern actions). +1. because they are explicitly addressed by the level-zero configuration, if the implementation defines it; this may concern menus and actions; +2. because these items were not addressed by any menu (but this may only concern actions). ## The level-zero case @@ -1407,7 +1406,7 @@ Though not strictly an action or a menu definition, the level-zero issue might b Ordering the elements which have to be displayed at the level-zero of the Filer context menu is just a particular case of a menu definition. -An implementation might define a `level-zero.directory` file, which would contain the ordered list of level zero items identified by their _desktop_file_id_. +An implementation might define a `level-zero.directory` file, which would contain the ordered list of level zero items identified by their `desktop_file_id`. The `[Desktop Entry]` section of this `level-zero.directory` file would so have only one of the following keys: @@ -1451,19 +1450,19 @@ The name `level-zero.directory` is chosen to not risk any collision with regular ## References -* [Desktop Entry Specification](http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html) -* [Desktop Menu Specification](http://standards.freedesktop.org/menu-spec/menu-spec-latest.html) -* [XDG Base Directory Specification](http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html) -* [Creating Konqueror Service Menus](http://developer.kde.org/documentation/tutorials/dot/servicemenus.html) -* [Krusader UserActions](http://www.krusader.org/handbook/useractions.html) -* [Thunar Custom Actions](http://thunar.xfce.org/pwiki/documentation/custom_actions) +* [Desktop Entry Specification](http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html) +* [Desktop Menu Specification](http://standards.freedesktop.org/menu-spec/menu-spec-latest.html) +* [XDG Base Directory Specification](http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html) +* [Creating Konqueror Service Menus](http://developer.kde.org/documentation/tutorials/dot/servicemenus.html) +* [Krusader UserActions](http://www.krusader.org/handbook/useractions.html) +* [Thunar Custom Actions](http://thunar.xfce.org/pwiki/documentation/custom_actions) ## Contributors -* Jonas Bähr -* David Faure -* Ted Gould -* Hong Jen Yee "PCMan" -* Michael Pyne -* Liam R. E. Quin -* Pierre Wieser +* Jonas Bähr +* David Faure +* Ted Gould +* Hong Jen Yee "PCMan" +* Michael Pyne +* Liam R. E. Quin +* Pierre Wieser diff --git a/developer/geom_rowr.md b/developer/geom_rowr.md index 7c90c0b5..e9323338 100644 --- a/developer/geom_rowr.md +++ b/developer/geom_rowr.md @@ -2,9 +2,9 @@ The `geom_rowr` kernel module for FreeBSD makes a read-only device writable by combining it with a read-write device. -``` .. note:: - This kernel module is currently under development and is being tested for adoption in helloSystem. -``` +:::{note} +This kernel module is currently under development and is being tested for adoption in helloSystem. +::: ## Use case @@ -27,33 +27,33 @@ As a result, immediately after creating the combined device, it appears to conta Execute the following commands as root: -``` -# Prepare filesystem image -dd if=/dev/zero of=test.img bs=1M count=512 -mdconfig -a -t vnode -f test.img -u 9 -newfs /dev/md9 -mount /dev/md9 /mnt -# Populate the filesystem -cp -R /boot/ /mnt -umount /mnt -mdconfig -d -u 9 - -# Load kernel module -kldload ./geom_rowr.ko -# prepare the read-only device md0 -mdconfig -a -t vnode -o readonly -f test.img -u 0 -# prepare the read-write device md1 -mdconfig -a -t swap -s 512M -u 1 -# Make sure the geom(8) tool will find the .so -cp geom_rowr.so /lib/geom -# Create the new device that combines md0 and md1 -geom rowr create rowr0 md0 md1 -mount /dev/rowr0 /mnt - -# See that the files are already there -ls /mnt -# make changes to the filesystem to see that it is read-write -mv /mnt/*.4th /mnt/lua; rm /mnt/pxeboot +```console +// Prepare filesystem image +# dd if=/dev/zero of=test.img bs=1M count=512 +# mdconfig -a -t vnode -f test.img -u 9 +# newfs /dev/md9 +# mount /dev/md9 /mnt +// Populate the filesystem +# cp -R /boot/ /mnt +# umount /mnt +# mdconfig -d -u 9 + +// Load kernel module +# kldload ./geom_rowr.ko +// prepare the read-only device md0 +# mdconfig -a -t vnode -o readonly -f test.img -u 0 +// prepare the read-write device md1 +# mdconfig -a -t swap -s 512M -u 1 +// Make sure the geom(8) tool will find the .so +# cp geom_rowr.so /lib/geom +// Create the new device that combines md0 and md1 +# geom rowr create rowr0 md0 md1 +# mount /dev/rowr0 /mnt + +// See that the files are already there +# ls /mnt +// make changes to the filesystem to see that it is read-write +# mv /mnt/*.4th /mnt/lua; rm /mnt/pxeboot ``` ## Use in the Live ISO boot process @@ -81,22 +81,22 @@ A swap-backed `md` device consumes close to zero memory when created and grows i Because `reroot` cannot be made to work with `geom_rowr` at this time, we need to use `chroot`. -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 - `/boot/kernel` and `/boot/modules` - will look differently inside vs. outside the chroot. +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. This can be fixed. Recommended way (to be tested): -Provided that `ramdisk.ufs` does not contain `/boot`, create a symlink on `ramdisk.ufs` from `/boot` to `/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 - `/boot/kernel` and `/boot/modules` - will look the same inside and outside of the chroot. +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. Alternative way (known to work): -``` -mkdir -p /sysroot/sysroot/boot # Needed? -mount -t nullfs /sysroot/boot /sysroot/sysroot/boot # Needed? +```console +# mkdir -p /sysroot/sysroot/boot # Needed? +# mount -t nullfs /sysroot/boot /sysroot/sysroot/boot # Needed? -echo "==> Set kernel module path for chroot" -sysctl kern.module_path=/sysroot/boot/kernel +# echo "==> Set kernel module path for chroot" +# sysctl kern.module_path=/sysroot/boot/kernel ``` ### ZFS @@ -107,7 +107,7 @@ With ZFS there is a problem unrelated to the `geom_rowr` code. When ZFS performs ## License -``` +```text geom_rowr.ko, geom_rowr.so: Copyright (c) 2021, Jordan Gordeev ``` diff --git a/developer/graphics.md b/developer/graphics.md index 1d7abeb6..97461125 100644 --- a/developer/graphics.md +++ b/developer/graphics.md @@ -6,7 +6,7 @@ helloSystem uses `initgfx` for the automatic configuration of the graphics hardw `initgfx` consists of the following files and directories: -``` +```text /etc/rc.d/initgfx /etc/initgfx_device.db /etc/initgfx_xorg.cfg @@ -29,8 +29,8 @@ driver depending on whether the system was booted via BIOS or EFI. If everything goes well, then after running `sudo sysctl initgfx start` you should have (example: Nvidia): -``` -% cat /usr/local/etc/X11/xorg.conf.d/00-video-initgfx.conf +```console +$ cat /usr/local/etc/X11/xorg.conf.d/00-video-initgfx.conf Section "Device" Identifier "NVIDIA CARD" VendorName "NVIDIA Corporation" @@ -66,7 +66,7 @@ Different versions of the Nvidia drivers exist. Unfortunately the latest version To check this: -``` -% cat /etc/rc.conf | grep initgfx_kmods +```console +$ cat /etc/rc.conf | grep initgfx_kmods initgfx_kmods="/usr/local/nvidia/390/boot/modules/nvidia.ko /usr/local/nvidia/390/boot/modules/nvidia-modeset.ko" ``` diff --git a/developer/linux.md b/developer/linux.md index e3b42315..21748aad 100644 --- a/developer/linux.md +++ b/developer/linux.md @@ -4,9 +4,9 @@ helloSystem is designed for use with helloSystem, which is based on FreeBSD. However, developers may want to verify that the code is reasonably platform independent by building on Linux from time to time. -``` .. note:: - That the code build does not necessarily mean that it works properly on Linux or that all features are implemented for Linux. -``` +:::{note} +That the code build does not necessarily mean that it works properly on Linux or that all features are implemented for Linux. +::: ## Building in a chroot on a FreeBSD host @@ -15,53 +15,53 @@ To verify that the code builds on Linux without needing a different development 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). When started for the first time, this downloads a minimal root filesystem. -``` -sudo service linux stop -sudo service debian stop -sudo service alpine onestart -sudo chroot /compat/alpine /bin/sh +```console +$ sudo service linux stop +$ sudo service debian stop +$ sudo service alpine onestart +$ sudo chroot /compat/alpine /bin/sh ``` In the chroot, build the essential helloSystem components -``` -# launch, open, and other essential command line tools that are required -git clone https://github.com/helloSystem/launch -mkdir -p launch/build -cd launch/build -grep ^apk ../README.md | sh -cmake .. -sudo make -j $(nproc) install -cd ../../ - -# Menu -git clone https://github.com/helloSystem/Menu -mkdir -p Menu/build -cd Menu/build -grep ^apk ../README.md | sh -cmake .. -sudo make -j $(nproc) install -cd ../../ - -# Filer -git clone https://github.com/helloSystem/Filer -mkdir -p Filer/build -cd Filer/build -grep ^apk ../README.md | sh -cmake .. -sudo make -j $(nproc) install -cd ../../ +```console +// launch, open, and other essential command line tools that are required +$ git clone https://github.com/helloSystem/launch +$ mkdir -p launch/build +$ cd launch/build +$ grep ^apk ../README.md | sh +$ cmake .. +$ sudo make -j $(nproc) install +$ cd ../../ + +// Menu +$ git clone https://github.com/helloSystem/Menu +$ mkdir -p Menu/build +$ cd Menu/build +$ grep ^apk ../README.md | sh +$ cmake .. +$ sudo make -j $(nproc) install +$ cd ../../ + +// Filer +$ git clone https://github.com/helloSystem/Filer +$ mkdir -p Filer/build +$ cd Filer/build +$ grep ^apk ../README.md | sh +$ cmake .. +$ sudo make -j $(nproc) install +$ cd ../../ ``` After you are done, -``` -sudo service alpine onestop +```console +$ sudo service alpine onestop ``` -``` .. note:: - If the compiler crashes, make sure that /usr/bin/clang++ is being used rather than /usr/bin/c++. This can be edited in CMakeCache.txt. -``` +:::{note} +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. +::: ## Running helloDesktop on Linux @@ -73,13 +73,16 @@ Run Alpine Linux, e.g., in VirtualBox on helloSystem, or on real hardware. * Enable community repo by `sed -i -e 's|^#||g' /etc/apk/repositories` * Install KDE Plasma using `setup-desktop`; set up a user * `rc-update add sddm` and `rc-service sddm start` -* Log into a KDE Plasma session on Alpine Linux. __Important:__ Select X11 session. Wayland doesn't work smoothly +* Log into a KDE Plasma session on Alpine Linux. + :::{important} + Select X11 session. Wayland doesn't work smoothly + ::: * Optionally, install VirtualBox related guest packages using `apk search` and `apk add` * `sudo su` to become root (there is no `sudo` configured on Alpine Linux by default) * Build and `make install` the three core components of helloDesktop (launch, Menu, and Filer) as above * From within the running KDE Plasma session, you can switch to the minimal helloDesktop with -``` +```sh #!/bin/sh launch Menu & @@ -94,18 +97,18 @@ The result will look somewhat like this: ![Screenshot](https://user-images.githubusercontent.com/2480569/200421869-96f81c37-0785-4416-ae43-bee920dd6a3e.png) -``` .. note:: - 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. -``` +:::{note} +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. +::: ## Building and running helloDesktop on Raspberry Pi -Loosely follow https://wiki.alpinelinux.org/wiki/Classic_install_or_sys_mode_on_Raspberry_Pi (not all commands seem to be working exactly as written anymore), but also create "Linux Swap" partition. Alternatively, in the running Alpine Linux system +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 -``` -fallocate -l 8G /swapfile -mkswap /swapfile -swapon /swapfile +```console +# fallocate -l 8G /swapfile +# mkswap /swapfile +# swapon /swapfile ``` to have enough RAM or else the compilation will be killed (at least on the 1GB and less RAM models). diff --git a/developer/localization.md b/developer/localization.md index 2fcdfa3d..1a621964 100644 --- a/developer/localization.md +++ b/developer/localization.md @@ -2,9 +2,7 @@ helloSystem is localized on [Hosted Weblate](https://hosted.weblate.org/projects/hellosystem/). - -Translation status - +[![Translation status](https://hosted.weblate.org/widgets/hellosystem/-/multi-auto.svg)](https://hosted.weblate.org/engage/hellosystem/) ## Contributing translations @@ -22,7 +20,7 @@ Follow the best practices for internationalization of Qt projects. To be documen 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: -``` +```py # Translate this application using Qt .ts files without the need for compilation import tstranslator tstr = tstranslator.TsTranslator(os.path.dirname(__file__) + "/i18n", "") @@ -32,7 +30,7 @@ def tr(input): In the class that defines your MainWindow or Wizard, do the following: -``` +```py class Wizard(QtWidgets.QWizard, object): def __init__(self): (...) @@ -45,18 +43,18 @@ class Wizard(QtWidgets.QWizard, object): To make new strings available for translation, a developer runs in the respective application directory: -``` -cd Resources/ -mkdir -p i18n +```console +$ cd Resources/ +$ mkdir -p i18n -# Create/update .ts file for English -pylupdate5 -noobsolete *.{py,ui} -ts i18n/en.ts +// Create/update .ts file for English +$ pylupdate5 -noobsolete *.{py,ui} -ts i18n/en.ts -# Remove unneeded location tags -xml ed -L -d '//location' i18n/en.ts +// Remove unneeded location tags +$ xml ed -L -d '//location' i18n/en.ts -# Remove translations from en, since en is not to be further translated -xml ed -L -d '//translation' i18n/en.ts +// Remove translations from en, since en is not to be further translated +$ xml ed -L -d '//translation' i18n/en.ts ``` Translators do not need to do this. diff --git a/developer/man.md b/developer/man.md index 737fff5b..477241ae 100644 --- a/developer/man.md +++ b/developer/man.md @@ -2,26 +2,26 @@ Command line tools should be shipped with man pages. -``` .. note:: - To make fullest use of all features, man pages should be written in their native markup language, mdoc. - - However, this has a quite steep learning curve, so the following can be used to get started quickly. -``` +:::{note} +To make fullest use of all features, man pages should be written in their native markup language, mdoc. + +However, this has a quite steep learning curve, so the following can be used to get started quickly. +::: One way to create man pages from Markdown is by using `pandoc` and the template from https://github.com/pragmaticlinuxblog/pandocmanpage. To convert Markdown to man: -``` -pandoc Desktop/launch.1.md -s -t man -o Desktop/launch.1 -/usr/bin/man ~/Desktop/launch.1 +```console +$ pandoc Desktop/launch.1.md -s -t man -o Desktop/launch.1 +$ /usr/bin/man ~/Desktop/launch.1 ``` To convert man to txt: -``` -/usr/bin/man ~/Desktop/launch.1 | col -b > ~/Desktop/launch.txt +```console +$ /usr/bin/man ~/Desktop/launch.1 | col -b > ~/Desktop/launch.txt ``` ## Order of sections diff --git a/developer/menu.md b/developer/menu.md index a7664128..bfbf8580 100644 --- a/developer/menu.md +++ b/developer/menu.md @@ -6,11 +6,11 @@ To provide this unified user experience, it is crucial that all applications can ## Terminology -``` .. note:: - Consistent, up-to-date documentation regarding the subject of global menus is hard to find. +:::{note} +Consistent, up-to-date documentation regarding the subject of global menus is hard to find. - Please consider submitting issues and pull requests if you can contribute to this subject. -``` +Please consider submitting issues and pull requests if you can contribute to this subject. +::: ### Concepts @@ -51,15 +51,15 @@ Those may or may not be used in helloSystem, they are mentioned here to give an The following libraries are involved in allowing applications to show their menu items in the global menu. -``` .. note:: - This list is probably incomplete. +:::{note} +This list is probably incomplete. - Please consider submitting issues and pull requests if you can contribute to this subject. -``` +Please consider submitting issues and pull requests if you can contribute to this subject. +::: ### libappindicator -``` +```text /usr/local/lib/libappindicator3.so.1 /usr/local/lib/libappindicator3.so.1.0.0 /usr/local/lib/libappindicator3.so @@ -77,7 +77,7 @@ The following libraries are involved in allowing applications to show their menu ### libappmenu-gtk-module library from vala-panel-appmenu repository -``` +```text /usr/local/lib/gtk-2.0/modules/libappmenu-gtk-module.so /usr/local/lib/gtk-3.0/modules/libappmenu-gtk-module.so ``` @@ -98,9 +98,9 @@ programs, converts to them MenuModel and send to them AppMenu Currently __not__ used in helloSystem. Do we need it? -``` +:::{note} tbd -``` +::: * Author: tbd * Description: tbd @@ -113,7 +113,7 @@ tbd ### libappmenu-gtk2-parser and libappmenu-gtk3-parser -``` +```text /usr/local/lib/libappmenu-gtk2-parser.so /usr/local/lib/libappmenu-gtk2-parser.so.0 /usr/local/lib/libappmenu-gtk3-parser.so @@ -131,7 +131,7 @@ tbd ### libdbusmenu-glib -``` +```text /usr/local/lib/libdbusmenu-glib.so /usr/local/lib/libdbusmenu-glib.so.4 /usr/local/lib/libdbusmenu-glib.so.4.0.12 @@ -149,7 +149,7 @@ information to be displayed to users of the application through the interface sh ### libdbusmenu-gtk3 -``` +```text /usr/local/lib/libdbusmenu-gtk3.so /usr/local/lib/libdbusmenu-gtk3.so.4 /usr/local/lib/libdbusmenu-gtk3.so.4.0.12 @@ -166,7 +166,7 @@ information to be displayed to users of the application through the interface sh ### libdbusmenu-qt5 -``` +```text /usr/local/lib/libdbusmenu-qt5.so /usr/local/lib/libdbusmenu-qt5.so.2 /usr/local/lib/libdbusmenu-qt5.so.2.6.0 @@ -183,7 +183,7 @@ information to be displayed to users of the application through the interface sh ### Kf5 Appmenu Plugin -``` +```text /usr/local/lib/qt5/plugins/kf5/kded/appmenu.so ``` @@ -198,7 +198,7 @@ information to be displayed to users of the application through the interface sh ### Kf5 Plasma Applet Appmenu Plugin -``` +```text /usr/local/lib/qt5/plugins/plasma/applets/plasma_applet_appmenu.so ``` @@ -213,7 +213,7 @@ information to be displayed to users of the application through the interface sh ### Kf5 Plasma Private libappmenuplugin -``` +```text /usr/local/lib/qt5/qml/org/kde/plasma/private/appmenu/libappmenuplugin.so ``` @@ -228,7 +228,7 @@ information to be displayed to users of the application through the interface sh ### wxGtk libwx_gtk3u_core -``` +```text /usr/local/lib/libwx_gtk3u_core-3.1.so /usr/local/lib/libwx_gtk3u_core-3.1.so.4 /usr/local/lib/libwx_gtk3u_core-3.1.so.4.0.0 @@ -258,7 +258,7 @@ Only if `GTK_MODULES=appmenu-gtk-module` is exported the menus in e.g. Audacity As of 2021, the (undocumented?) `UBUNTU_MENUPROXY` environment variable is referenced in -``` +```text /usr/local/lib/libwx_gtk3u_core-3.1.so.4.0.0 /usr/local/lib/gtk-3.0/modules/libappmenu-gtk-module.so /usr/local/lib/gtk-2.0/modules/libappmenu-gtk-module.so @@ -271,13 +271,13 @@ Audacity is an example for an application that uses `libwx_gtk3u_core-3.1.so.4`. * Apparently setting it to a random value still makes the global menu work for Audacity * According to [this](https://github.com/electron/electron/issues/709#issuecomment-59207492), `UBUNTU_MENUPROXY` should be set to `libappmenu.so`? -``` .. note:: - Please consider submitting issues and pull requests if you know how UBUNTU_MENUPROXY is supposed to work. Is it documented? -``` +:::{note} +Please consider submitting issues and pull requests if you know how UBUNTU_MENUPROXY is supposed to work. Is it documented? +::: Ultimaker Cura (which does not have a working global menu integration by default) contains a note in `/usr/local/lib/python3.7/site-packages/UM/Application.py` saying -``` +```py # For Ubuntu Unity this makes Qt use its own menu bar rather than pass it on to Unity. os.putenv("UBUNTU_MENUPROXY", "0") ``` @@ -310,8 +310,8 @@ Packages of patched Firefox and Thunderbird are available at http://build.schmit helloSystem versions 0.7.0 and up come with this repository enabled. To enable it manually: -``` -cat > /usr/local/etc/pkg/repos/helloDesktop.conf <<\EOF +```console +$ cat > /usr/local/etc/pkg/repos/helloDesktop.conf <<\EOF helloDesktop: { url: "pkg+http://build.schmitz.computer/packages/${ABI}-mozillapatched", mirror_type: "srv", @@ -322,7 +322,7 @@ helloDesktop: { } EOF -cat > /usr/local/etc/ssl/certs/jsm222.cert <<\EOF +$ cat > /usr/local/etc/ssl/certs/jsm222.cert <<\EOF -----BEGIN PUBLIC KEY----- MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA5gEt92AHUkYkZH2Q2nP3 2/Wu7gxbMEno5iqi1ea327lHmhJB18E0mW9dKYgxz74PbbTAmyaMdY4G1vn3cStp @@ -339,12 +339,12 @@ q9cTv5oaRy9FQy0NdGwGuqUCAwEAAQ== -----END PUBLIC KEY----- EOF -sudo pkg install firefox thunderbird +$ sudo pkg install firefox thunderbird ``` Since the helloDesktop repository has `priority: 100`, you should see: -``` +```console New packages to be INSTALLED: firefox-94.0.1_1,2 [helloDesktop] thunderbird: 91.3.0_1 [helloDesktop] @@ -354,7 +354,7 @@ Note the `helloDesktop`, indicating that these packages will be installed from t ### GMenu-DBusMenu-Proxy -``` +```text /usr/local/bin/gmenudbusmenuproxy ``` @@ -372,9 +372,9 @@ Note the `helloDesktop`, indicating that these packages will be installed from t The __Qt 5 D-Bus Viewer__ utility may be useful in debugging global menus. -``` .. note:: - Please consider submitting issues and pull requests if you can contribute to this subject. -``` +:::{note} +Please consider submitting issues and pull requests if you can contribute to this subject. +::: ### Getting the menus for a Qt application knowing the Xorg window ID @@ -402,11 +402,11 @@ The __Qt 5 D-Bus Viewer__ utility may be useful in debugging global menus. Applications running as root currently cannot show global menus due to the D-Bus architecture. -``` .. note:: - Possibly some sort of proxy would be needed to allow applications that were invoked via `sudo -E` to display their menus in the global menu of the user running the desktop session. - - Please consider contributing ideas and code if you are interested in this topic. -``` +:::{note} +Possibly some sort of proxy would be needed to allow applications that were invoked via `sudo -E` to display their menus in the global menu of the user running the desktop session. + +Please consider contributing ideas and code if you are interested in this topic. +::: ## Implementations for other desktop systems diff --git a/developer/midi.md b/developer/midi.md index 0bc2506b..9b34ca3d 100644 --- a/developer/midi.md +++ b/developer/midi.md @@ -6,41 +6,41 @@ Over a decade ago, someone [wrote](https://forums.freebsd.org/threads/alsa-midi- This page describes how to use USB based hardware MIDI controllers (e.g., keyboards), with helloSystem and FreeBSD. -``` .. note:: - It is a work in progress. Please consider contributing additions and corrections. -``` +:::{note} +It is a work in progress. Please consider contributing additions and corrections. +::: ## Using /dev/umidi* -Whenever a USB based hardware MIDI controller is plugged into the computer, a `/dev/umidi*` device node is created automatically. +Whenever a USB based hardware MIDI controller is plugged into the computer, a {file}`/dev/umidi*` device node is created automatically. ### Testing To test whether input from the MIDI controller arrives, run in a Terminal window: -``` -midicat -d -q rmidi/0.0 -o /dev/null +```console +$ midicat -d -q rmidi/0.0 -o /dev/null ``` 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`. -Some applications can use `/dev/umidi*` device nodes directly. Some expect the device node to be at `/dev/midi` though, so you need to create a symlink there manually. +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. ### Example application For example, the `fluidsynth` command line tool, can use hardware MIDI controllers in this way directly: -``` -sudo pkg install -y fluidsynth musescore -sudo ln -sf /dev/umidi*.0 /dev/midi -fluidsynth -m oss -a oss SoundFont.sf2 +```console +$ sudo pkg install -y fluidsynth musescore +$ sudo ln -sf /dev/umidi*.0 /dev/midi +$ fluidsynth -m oss -a oss SoundFont.sf2 ``` -Unfortunately, not all applications on FreeBSD can use `/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. +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. -``` .. note:: - Applications cannot access /dev/umidi* directly while alsa-seq-server is running. -``` +:::{note} +Applications cannot access /dev/umidi* directly while alsa-seq-server is running. +::: ## Using OSS Raw-MIDI (Open Sound System) @@ -60,23 +60,23 @@ Some applications can use `alsa-seq-server` to access MIDI controllers. For some In order for applications that use `alsa-seq-server` to talk to your MIDI controller, run -``` -sudo pkg install alsa-seq-server alsa-utils -sudo alsa-seq-server -d /dev/umidi* +```console +$ sudo pkg install alsa-seq-server alsa-utils +$ sudo alsa-seq-server -d /dev/umidi* ``` and then run the application. -``` .. note:: - 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. -``` +:::{note} +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. +::: ### Testing To test whether input from the MIDI controller arrives, run in a separate Terminal: -``` -aseqdump -p 0 +```console +$ aseqdump -p 0 Waiting for data. Press Ctrl+C to end. Source Event Ch Data ``` @@ -89,7 +89,7 @@ An example application that can use `alsa-seq-server` to talk to MIDI controller 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: -``` +```text CMAKE_OFF= WANT_CALF WANT_CAPS WANT_CMT WANT_SWH WANT_STK \ WANT_TAP WANT_VST CMAKE_ON= WANT_QT5 WANT_ALSA @@ -101,7 +101,7 @@ To use it, select "ALSA-Sequencer (Advanced Linux Sound Architecture)" from the If you see -``` +```console ALSA lib seq_hw.c:466:(snd_seq_hw_open) open /dev/snd/seq failed: No such file or directory cannot open sequencer: No such file or directory ``` diff --git a/developer/monkey-patch.md b/developer/monkey-patch.md index 79179658..45d034db 100644 --- a/developer/monkey-patch.md +++ b/developer/monkey-patch.md @@ -4,9 +4,9 @@ Starting with helloSystem 0.7.0 it is possible to [monkey patch](https://en.wiki With that, it allows for a very rapid development-test cycle for Live ISOs. -``` .. note:: - This feature is currently under active development and its usage is still subject to change. -``` +:::{note} +This feature is currently under active development and its usage is still subject to change. +::: ## Theory of operation @@ -33,7 +33,9 @@ The code inside the file `monkeypatch.sh` on the volume called `MONKEYPATCH` wil ## Example `monkeypatch.sh` file -``` +```shell +#!/bin/sh + # Write a file echo "HELLO MONKEY" > /tmp/MONKEY_WAS_HERE @@ -59,26 +61,26 @@ chmod +x /usr/local/sbin/mount_md A particularly effective way to debug the late boot process (after Xorg has started) is: -``` -mv /usr/local/bin/start-hello /usr/local/bin/start-hello.real -cat > /usr/local/bin/start-hello <<\EOF +```sh +$ mv /usr/local/bin/start-hello /usr/local/bin/start-hello.real +$ cat > /usr/local/bin/start-hello << EOF #!/bin/sh xterm -maximized start-hello.real # xterm -maximized EOF -chmod +x /usr/local/bin/start-hello* +$ chmod +x /usr/local/bin/start-hello* ``` This will allow you to see the commands in `start-hello.real` as they are executed. ## Booting a Live ISO running a different `init_script` -If you would like to test changes to `/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: +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: -* Boot the ISO but interrupt the bootloader by pressing the Esc key +* Boot the ISO but interrupt the bootloader by pressing the {kbd}`Esc` key * At the boot prompt, enter: `set monkey_patch_init_script=YES` * Optionally, use `unset BOOT_MUTE` so that you can see messages on the screen during boot * Start the system by entering `boot` -The code inside the file `init_script` on the volume called `MONKEYPATCH` will be executed instead of `/boot/init_script` on the ISO. +The code inside the file `init_script` on the volume called `MONKEYPATCH` will be executed instead of {file}`/boot/init_script` on the ISO. diff --git a/developer/ports.md b/developer/ports.md index 79e4ce36..712a9375 100644 --- a/developer/ports.md +++ b/developer/ports.md @@ -1,6 +1,7 @@ # Working with FreeBSD Ports In some situations it may be necessary to make changes to existing software that comes in FreeBSD packages. + This section describes how to make such changes using an example. ## Example @@ -17,81 +18,82 @@ Here is how to do it using FreeBSD Ports: ## Pulling the ports tree -``` -sudo git clone https://git.freebsd.org/ports.git /usr/ports --depth=1 +```console +$ sudo git clone https://git.freebsd.org/ports.git /usr/ports --depth=1 ``` If you are running an end-of-life FreeBSD version such as 12.1, you also need to -``` -export ALLOW_UNSUPPORTED_SYSTEM=1 -# Or in csh -setenv ALLOW_UNSUPPORTED_SYSTEM YES +```console +$ export ALLOW_UNSUPPORTED_SYSTEM=1 +// Or in csh +% setenv ALLOW_UNSUPPORTED_SYSTEM YES ``` ## Building the port without changes Build the port without changes first to ensure it builds and works as expected. -``` -cd /usr/ports/x11-toolkits/qtermwidget/ +```console +$ cd /usr/ports/x11-toolkits/qtermwidget/ -# Install all build-time dependencies from packages -make build-depends-list | cut -c 12- | xargs pkg install -y +// Install all build-time dependencies from packages +$ make build-depends-list | cut -c 12- | xargs pkg install -y -# Build the library -# NOTE: Applications that have a library that is used by nothing but that application are just -# annoying because now you have to deal with two entities rather than one -MAKE_JOBS_UNSAFE=yes sudo -E make -j4 +// Build the library +// NOTE: Applications that have a library that is used by nothing but that application are just +// annoying because now you have to deal with two entities rather than one +$ MAKE_JOBS_UNSAFE=yes sudo -E make -j4 -# Now, the application itself -cd /usr/ports/x11/qterminal +// Now, the application itself +$ cd /usr/ports/x11/qterminal -# Install all build-time dependencies from packages -make build-depends-list | cut -c 12- | xargs pkg install -y +// Install all build-time dependencies from packages +$ make build-depends-list | cut -c 12- | xargs pkg install -y -# Build the application -QTermWidget5_DIR=/usr/ports/x11-toolkits/qtermwidget/work/stage/usr/local/lib/cmake/qtermwidget5/ MAKE_JOBS_UNSAFE=yes sudo -E make -j4 +// Build the application +$ QTermWidget5_DIR=/usr/ports/x11-toolkits/qtermwidget/work/stage/usr/local/lib/cmake/qtermwidget5/ MAKE_JOBS_UNSAFE=yes sudo -E make -j4 -# Run the application with the changed library -LD_LIBRARY_PATH=/usr/ports/x11-toolkits/qtermwidget/work/stage/usr/local/lib/ /usr/ports/x11/qterminal/work/stage/usr/local/bin/qterminal +// Run the application with the changed library +$ LD_LIBRARY_PATH=/usr/ports/x11-toolkits/qtermwidget/work/stage/usr/local/lib/ /usr/ports/x11/qterminal/work/stage/usr/local/bin/qterminal ``` ## Making changes to the port Now make changes to the port. -``` .. note:: - In the ports system you cannot just change the source code because it would be overwritten during the build process. +:::{note} +In the ports system you cannot just change the source code because it would be overwritten during the build process. + 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. -``` +::: -``` -# Copy the file to be changed -cd /usr/ports/x11-toolkits/qtermwidget -sudo cp work/qtermwidget-*/lib/TerminalDisplay.cpp work/qtermwidget-*/lib/TerminalDisplay.cpp.orig +```console +// Copy the file to be changed +$ cd /usr/ports/x11-toolkits/qtermwidget +$ sudo cp work/qtermwidget-*/lib/TerminalDisplay.cpp work/qtermwidget-*/lib/TerminalDisplay.cpp.orig -# Make the change in the library -sudo nano work/qtermwidget-*/lib/TerminalDisplay.cpp +// Make the change in the library +$ sudo nano work/qtermwidget-*/lib/TerminalDisplay.cpp QChar q(QLatin1Char('\'')); dropText += q + QString(urlText).replace(q, QLatin1String("'\\''")) + q; dropText += QLatin1Char(' '); -# Make a patch -sudo make makepatch +// Make a patch +$ sudo make makepatch -# Build the library again -# sudo make clean # Run this only if the next line does nothing -MAKE_JOBS_UNSAFE=yes sudo -E make -j4 +// Build the library again +$ sudo make clean # Run this only if the next line does nothing +$ MAKE_JOBS_UNSAFE=yes sudo -E make -j4 -# Run the application with the changed library -LD_LIBRARY_PATH=/usr/ports/x11-toolkits/qtermwidget/work/stage/usr/local/lib/ /usr/ports/x11/qterminal/work/stage/usr/local/bin/qterminal +// Run the application with the changed library +$ LD_LIBRARY_PATH=/usr/ports/x11-toolkits/qtermwidget/work/stage/usr/local/lib/ /usr/ports/x11/qterminal/work/stage/usr/local/bin/qterminal ``` As a result we have a patch: -``` -% cat files/patch-lib_TerminalDisplay.cpp +```console +$ cat files/patch-lib_TerminalDisplay.cpp --- lib/TerminalDisplay.cpp.orig 2020-11-03 08:19:26 UTC +++ lib/TerminalDisplay.cpp @@ -3099,7 +3099,9 @@ void TerminalDisplay::dropEvent(QDropEvent* event) @@ -111,16 +113,16 @@ As a result we have a patch: Optionally, make packages for the ports. Note that `make build` needs to have run already before this step. -``` -# Library -cd /usr/ports/x11-toolkits/qtermwidget/ -sudo make package -ls work/pkg - -# Application -cd /usr/ports/x11/qterminal -sudo make package -ls work/pkg +```console +// Library +$ cd /usr/ports/x11-toolkits/qtermwidget/ +$ sudo make package +$ ls work/pkg + +// Application +$ cd /usr/ports/x11/qterminal +$ sudo make package +$ ls work/pkg ``` ## Creating a port from scratch @@ -128,28 +130,28 @@ ls work/pkg 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. -``` .. note:: - This section is a work in progress. Corrections are welcome. -``` +:::{note} +This section is a work in progress. Corrections are welcome. +::: First, prepare the Ports environment: -``` -sudo su -pkg install portlint -echo DEVELOPER=yes >> /etc/make.conf +```console +$ sudo su +# pkg install portlint +# echo DEVELOPER=yes >> /etc/make.conf ``` Next, create a directory for the new port: -``` -mkdir /usr/ports/sysutils/fluxengine -cd /usr/ports/sysutils/fluxengine +```console +# mkdir /usr/ports/sysutils/fluxengine +# cd /usr/ports/sysutils/fluxengine ``` Create `Makefile` with the following content: -``` +```text # $FreeBSD$ PORTNAME= fluxengine @@ -182,8 +184,8 @@ do-install: Run -``` -make makeplist > pkg-plist +```console +# make makeplist > pkg-plist ``` to create that file. Check and edit it by hand, especially the first line. @@ -197,7 +199,7 @@ Notes Create `pkg-descr` based on the description on the GitHub [README.md](https://github.com/davidgiven/fluxengine): -``` +```text The FluxEngine is a very cheap USB floppy disk interface capable of reading and writing exotic non-PC floppy disk formats. It allows you to use a conventional PC drive to accept Amiga disks, @@ -217,34 +219,34 @@ Notes Create the checksum file by running -``` -make makesum +```console +# make makesum ``` Check the Makefile with -``` -portlint +```console +# portlint ``` and correct any mistakes it reports, then repeat. Once `portlint` says `looks fine`, try to build by running -``` -make +```console +# make ``` Note that the compilation will fail. This is because in this case the application needs to be built with `gmake` rather than `make`. Run tests -``` -make stage -make stage-qa -make package -make install -make deinstall +```console +# make stage +# make stage-qa +# make package +# make install +# make deinstall ``` 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,42 +255,43 @@ At this point it may be a good idea to have an experienced FreeBSD Ports develop Once everything looks good, prepare a `.shar` file for submitting it to https://bugs.freebsd.org/submit/: -``` -rm -rf work/ -cd .. -tar cf fluxengine.shar --format shar fluxengine +```console +# rm -rf work/ +# cd .. +# tar cf fluxengine.shar --format shar fluxengine ``` ## Updating existing ports This real-life example shows how to update a port, e.g., `x11/qterminal`. -``` -sudo su -cd /usr/ports -git pull -cd x11/qterminal +```console +$ sudo su +# cd /usr/ports +# git pull +# cd x11/qterminal ``` 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. -``` -portlint # Fix errors, if any -rm pkg-plist -make clean -make package reinstall -make makeplist > pkg-plist -nano pkg-plist # Remove first line and check the others -make clean -make package reinstall +```console +# portlint # Fix errors, if any +# rm pkg-plist +# make clean +# make package reinstall +# make makeplist > pkg-plist +# nano pkg-plist # Remove first line and check the others +# make clean +# make package reinstall ``` Finally, once everything is tested, create separate patches for each port with -``` -cd /usr/ports -git diff -U999999 x11/qterminal > /home/user/Desktop/x11_qterminal.diff -git diff -U999999 devel/lxqt-build-tools > /home/user/Desktop/devel_lxqt-build-tools.diff -git diff -U999999 x11-toolkits/qtermwidget > /home/user/Desktop/x11-toolkits_qtermwidget.diff + +```console +# cd /usr/ports +# git diff -U999999 x11/qterminal > /home/user/Desktop/x11_qterminal.diff +# git diff -U999999 devel/lxqt-build-tools > /home/user/Desktop/devel_lxqt-build-tools.diff +# git diff -U999999 x11-toolkits/qtermwidget > /home/user/Desktop/x11-toolkits_qtermwidget.diff ``` 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. diff --git a/developer/rpi.md b/developer/rpi.md index 0e28ef45..b7c389ef 100644 --- a/developer/rpi.md +++ b/developer/rpi.md @@ -6,7 +6,9 @@ Although we are currently not providing installation images for Raspberry Pi, we 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. -> __Note:__ 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. +:::{note} +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. +::: 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. @@ -33,7 +35,7 @@ If there is enough interest, we might eventually provide readymade helloSystem i * 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 * Edit `config.txt` in the `MSDOSBOOT` partition to contain the correct resolution for your screen. -``` +```text hdmi_safe=0 disable_overscan=1 display_auto_detect=1 @@ -46,22 +48,23 @@ gpu_mem=512 dtoverlay=vc4-kms-v3d-pi4 ``` -``` .. note:: +:::{note} If, for some reason, the display does not work, simply remove or comment out the `max_framebuffer*` lines and replace them with the following: -``` -``` + +```text framebuffer_width= framebuffer_height= ``` +::: ## Preparing a bootable SSD drive (optional but recommended) * [Update your firmware if USB boot is not working](https://www.raspberrystreet.com/learn/how-to-boot-raspberrypi-from-usb-ssd) * Follow the instructions in the SD card section, but write the image to your SSD -``` .. note:: +:::{note} 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. -``` +::: ## Booting into the system @@ -76,17 +79,17 @@ We will be doing all subsequent steps on the Raspberry Pi system itself since we * Log in with `root`, password `root` * Install some basic software with `pkg install -y xorg xterm nano openbox fluxbox git-lite` -``` .. note:: +:::{note} `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 -``` +::: ## Starting a graphical session Start Xorg with -``` -echo startfluxbox > ~/.xinitrc -startx +```console +# echo startfluxbox > ~/.xinitrc +# startx ``` Doing it like this is the easiest way since the display `DISPLAY` environment variable and other things will be set automatically. @@ -95,86 +98,86 @@ Doing it like this is the easiest way since the display `DISPLAY` environment va ### Install prerequisites -``` -pkg install -y cmake pkgconf qt5-qmake qt5-buildtools kf5-kdbusaddons kf5-kwindowsystem libdbusmenu-qt5 qt5-concurrent qt5-quickcontrols2 libfm libqtxdg wget +```console +# pkg install -y cmake pkgconf qt5-qmake qt5-buildtools kf5-kdbusaddons kf5-kwindowsystem libdbusmenu-qt5 qt5-concurrent qt5-quickcontrols2 libfm libqtxdg wget ``` ### launch The `launch` command is central to helloSystem and is used to launch applications throughout the system. -``` -git clone https://github.com/helloSystem/launch -cd launch/ -mkdir build -cd build/ -cmake .. -make -j4 -./launch -make install -cd ../../ +```console +# git clone https://github.com/helloSystem/launch +# cd launch/ +# mkdir build +# cd build/ +# cmake .. +# make -j4 +# ./launch +# make install +# cd ../../ ``` ### Menu -``` -git clone https://github.com/helloSystem/Menu -cd Menu -mkdir build -cd build -cmake .. -make -j4 -make install -ln -s /usr/local/bin/menubar /usr/local/bin/Menu # Workaround for the 'launch' command to find it -cd ../../ +```console +# git clone https://github.com/helloSystem/Menu +# cd Menu +# mkdir build +# cd build +# cmake .. +# make -j4 +# make install +# ln -s /usr/local/bin/menubar /usr/local/bin/Menu # Workaround for the 'launch' command to find it +# cd ../../ ``` ### Filer -``` -git clone https://github.com/helloSystem/Filer -cd Filer/ -mkdir build -cd build/ -cmake .. -make -j4 -make install -ln -s /usr/local/bin/filer-qt /usr/local/bin/Filer # Workaround for the 'launch' command to find it -cd ../../ +```console +# git clone https://github.com/helloSystem/Filer +# cd Filer/ +# mkdir build +# cd build/ +# cmake .. +# make -j4 +# make install +# ln -s /usr/local/bin/filer-qt /usr/local/bin/Filer # Workaround for the 'launch' command to find it +# cd ../../ ``` -``` .. note:: +:::{note} 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. -``` +::: ### Dock -``` -pkg install -y <...> -git clone https://github.com/helloSystem/Dock -cd Dock -mkdir build -cd build -cmake .. -make -j4 -make install -# Currently Dock is installed to /usr/bin/cyber-dock. In the future is should be in /usr/local/bin/. -ln -s /usr/bin/cyber-dock /usr/local/bin/Dock # Workaround for the 'launch' command to find it -cd ../../ +```console +# pkg install -y <...> +# git clone https://github.com/helloSystem/Dock +# cd Dock +# mkdir build +# cd build +# cmake .. +# make -j4 +# make install +// Currently Dock is installed to /usr/bin/cyber-dock. In the future is should be in /usr/local/bin/. +# ln -s /usr/bin/cyber-dock /usr/local/bin/Dock # Workaround for the 'launch' command to find it +# cd ../../ ``` ### QtPlugin -``` -git clone https://github.com/helloSystem/QtPlugin -cd QtPlugin/ -mkdir build -cd build/ -cmake .. -make -j4 -make install -cp ../stylesheet.qss /usr/local/etc/xdg/ -cd ../../ +```console +# git clone https://github.com/helloSystem/QtPlugin +# cd QtPlugin/ +# mkdir build +# cd build/ +# cmake .. +# make -j4 +# make install +# cp ../stylesheet.qss /usr/local/etc/xdg/ +# cd ../../ ``` ### Icons and other assets @@ -183,27 +186,26 @@ Install icons and other helloSystem assets that are not packaged as FreeBSD pack For the system icons: -``` -wget -c -q http://archive.ubuntu.com/ubuntu/pool/universe/x/xubuntu-artwork/xubuntu-icon-theme_16.04.2_all.deb -tar xf xubuntu-icon-theme_16.04.2_all.deb -tar xf data.tar.xz -mkdir -p "${uzip}"/usr/local/share/icons/ -mv ./usr/share/icons/elementary-xfce "${uzip}"/usr/local/share/icons/ -mv ./usr/share/doc/xubuntu-icon-theme/copyright "${uzip}"/usr/local/share/icons/elementary-xfce/ -sed -i -e 's|usr/share|usr/local/share|g' "${uzip}"/usr/local/share/icons/elementary-xfce/copyright -rm "${uzip}"/usr/local/share/icons/elementary-xfce/copyright-e - -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 +```console +# wget -c -q http://archive.ubuntu.com/ubuntu/pool/universe/x/xubuntu-artwork/xubuntu-icon-theme_16.04.2_all.deb +# tar xf xubuntu-icon-theme_16.04.2_all.deb +# tar xf data.tar.xz +# mkdir -p "${uzip}"/usr/local/share/icons/ +# mv ./usr/share/icons/elementary-xfce "${uzip}"/usr/local/share/icons/ +# mv ./usr/share/doc/xubuntu-icon-theme/copyright "${uzip}"/usr/local/share/icons/ elementary-xfce/ +# sed -i -e 's|usr/share|usr/local/share|g' "${uzip}"/usr/local/share/icons/elementary-xfce/copyright +# rm "${uzip}"/usr/local/share/icons/elementary-xfce/copyright-e +# 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 ``` For the system fonts: -``` -wget -c -q https://github.com/ArtifexSoftware/urw-base35-fonts/archive/20200910.zip -unzip -q 20200910.zip -mkdir -p "${uzip}/usr/local/share/fonts/TTF/" -cp -R urw-base35-fonts-20200910/fonts/*.ttf "${uzip}/usr/local/share/fonts/TTF/" -rm -rf urw-base35-fonts-20200910/ 20200910.zip +```console +# wget -c -q https://github.com/ArtifexSoftware/urw-base35-fonts/archive/20200910.zip +# unzip -q 20200910.zip +# mkdir -p "${uzip}/usr/local/share/fonts/TTF/" +# cp -R urw-base35-fonts-20200910/fonts/*.ttf "${uzip}/usr/local/share/fonts/TTF/" +# rm -rf urw-base35-fonts-20200910/ 20200910.zip ``` Proceed similarly for the cursor theme, wallpaper, applications from the helloSystem/Utilities repository, and other assets. @@ -212,13 +214,15 @@ Proceed similarly for the cursor theme, wallpaper, applications from the helloSy Install every package that is not commented out in [packages.hello](https://raw.githubusercontent.com/helloSystem/ISO/experimental/settings/packages.hello) that are installable. -``` .. note:: - 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. -``` +:::{note} +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. +::: You can use this script to automatically install all listed packages: ```sh +#!/bin/sh + url="https://raw.githubusercontent.com/helloSystem/ISO/experimental/settings/packages.hello" curl -fsS $url | egrep -v '^#' | while read line ; do pkg install -y -U $line || echo "[error] $line cannot be installed" @@ -229,23 +233,23 @@ To enable `automount`, run `service devd restart`. ### Installing overlays -``` -git clone https://github.com/helloSystem/ISO -cp -Rfv ISO/overlays/uzip/hello/files/ / -cp -Rfv ISO/overlays/uzip/localize/files/ / -cp -Rfv ISO/overlays/uzip/openbox-theme/files/ / -cp -Rfv ISO/overlays/uzip/mountarchive/files/ / +```console +# git clone https://github.com/helloSystem/ISO +# cp -Rfv ISO/overlays/uzip/hello/files/ / +# cp -Rfv ISO/overlays/uzip/localize/files/ / +# cp -Rfv ISO/overlays/uzip/openbox-theme/files/ / +# cp -Rfv ISO/overlays/uzip/mountarchive/files/ / ``` -``` .. note:: - 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. -``` +:::{note} +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. +::: ## Adjusting fstab -Edit `/etc/fstab` to look like this: +Edit {file}`/etc/fstab` to look like this: -``` +```text /dev/mmcsd0s2a / ufs rw 0 0 ``` @@ -255,7 +259,7 @@ Otherwise the root device may not be found upon reboot. 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: -``` +```text dbus_enable="YES" avahi_enable="YES" ``` @@ -266,7 +270,7 @@ and then start it `service dbus start`. Edit the `start-hello` script to use the `launch` command instead of hardcoding `/Applications/...`. -``` +```text ################################# # Details to be inserted here. # This script is work in progress. @@ -275,9 +279,9 @@ Edit the `start-hello` script to use the `launch` command instead of hardcoding ### Starting helloDesktop session -``` -echo start-hello > ~/.xinitrc -killall Xorg +```console +# echo start-hello > ~/.xinitrc +# killall Xorg ``` Type `startx` to start an Xorg session; it should now load a helloDesktop session. @@ -288,31 +292,36 @@ Sometimes it does not load all the way, in this case it is necessary to start xt Added a new user with Applications -> Preferences -> Users -``` -cp /home/user/.openbox* . -cp -r /home/user/.config/* .config/ +```console +# cp /home/user/.openbox* . +# cp -r /home/user/.config/* .config/ ``` ## Improving system performance ### Setting up SWAP for greater system memory capabilities -``` .. note:: - 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. -``` +:::{note} +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. +::: * Create a SWAP file using -``` -# dd if=/dev/zero of=/swap bs=1M count=8192 -``` -``` .. note:: -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. -``` + + ```console + # dd if=/dev/zero of=/swap bs=1M count=8192 + ``` + + :::{note} + 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. + ::: + * Run `# chmod 0600 /swap` to give it the correct permissions. * Edit /etc/fstab and append the following line: -``` -md42 none swap sw,file=/swap 0 0 -``` + + ```text + md42 none swap sw,file=/swap 0 0 + ``` + * Run `# swapon -aq` to immediately enable SWAP * Run `$ swapinfo -k` to verify that it's been attached correctly @@ -322,9 +331,9 @@ With an SSD, SWAP, and several GPU enhancements enabled, you should immediately 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. -To overclock you Raspberry Pi 4 to the max, edit `/boot/msdos/config.txt` and append the following: +To overclock you Raspberry Pi 4 to the max, edit {file}`/boot/msdos/config.txt` and append the following: -``` +```text over_voltage=6 arm_freq=2147 gpu_freq=700 @@ -334,9 +343,9 @@ gpu_freq=700 ## Known issues -``` .. note:: - Any help in improving the situation is appreciated. -``` +:::{note} +Any help in improving the situation is appreciated. +::: Not sure whether `vc4-kms-v3d` is usable with FreeBSD. @@ -346,15 +355,15 @@ Also see: https://papers.freebsd.org/2019/bsdcan/vadot-adventure_in_drmland/ The `slim` package is missing, hence we don't have a login window at the moment. -``` .. note:: - Web browser performance may be improved and the following issues may not be relevant anymore. This will require more user feedback and testing. -``` +:::{note} +Web browser performance may be improved and the following issues may not be relevant anymore. This will require more user feedback and testing. +::: ### Web browser 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: -``` +```console # cat /root/.config/falkon/crashlog/Crash-2021-04-17T10:21:20.txt Time: Sa. Apr. 17 10:21:20 2021 Qt version: 5.15.2 (compiled with 5.15.2) @@ -366,9 +375,9 @@ Rendering engine: QtWebEngine #1: 0x499b4994 <_pthread_sigmask+0x524> at /lib/libthr.so.3 ``` -``` .. note:: - The exact same crash also happens on a RockPro64 with 4GB of RAM. -``` +:::{note} +The exact same crash also happens on a RockPro64 with 4GB of RAM. +::: ### RAM compression @@ -380,23 +389,23 @@ Windows also does RAM compression: https://www.tenforums.com/windows-10-news/179 The following seems to "work" but can make the Raspberry Pi unacceptably slow: -``` -mdconfig -a -t malloc -o compress -o reserve -s 700m -u 7 -swapon /dev/md7 +```console +# mdconfig -a -t malloc -o compress -o reserve -s 700m -u 7 +# swapon /dev/md7 ``` -``` .. note:: - Please let us know if you know how to properly use RAM compression on FreeBSD. -``` +:::{note} +Please let us know if you know how to properly use RAM compression on FreeBSD. +::: -``` .. note:: - Do not use ZFS on memory-constrained machines. -``` +:::{note} +Do not use ZFS on memory-constrained machines. +::: ### Missing icons Set `QT_QPA_PLATFORMTHEME` env variable before staring Xorg session. -``` +```console setenv QT_QPA_PLATFORMTHEME panda ``` diff --git a/developer/tracing.md b/developer/tracing.md index b42b8a0e..245ce67f 100644 --- a/developer/tracing.md +++ b/developer/tracing.md @@ -2,21 +2,23 @@ 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. -``` -sudo pkg install dtrace-toolkit -sudo kldload dtraceall -launch FeatherPad -# In another terminal: ps ax | grep featherpad -# Then use the PID of the featherpad process for the next command: -sudo dtruss -p 1886 -f +```console +$ sudo pkg install dtrace-toolkit +$ sudo kldload dtraceall +$ launch FeatherPad +// In another terminal: +$ ps ax | grep featherpad +// Then use the PID of the featherpad process for the next command: +$ sudo dtruss -p 1886 -f ``` -``` .. note:: - If you get `probe description syscall:::entry does not match any probes`, then possibly you loaded `kldload dtrace` rather than `kldload dtraceall`. -``` +:::{note} +If you get `probe description syscall:::entry does not match any probes`, then possibly you loaded `kldload dtrace` rather than `kldload dtraceall`. +::: The [FreeBSD DTrace Tutorial](https://wiki.freebsd.org/DTrace/Tutorial) has many one-liner examples for tasks like observing + * File Opens * Syscall Counts By Process * Distribution of read() Bytes @@ -30,6 +32,6 @@ The [FreeBSD DTrace Tutorial](https://wiki.freebsd.org/DTrace/Tutorial) has many There is also a full list of [DTrace One-Liners](https://wiki.freebsd.org/DTrace/One-Liners) to pick up more DTrace functionality. -``` .. note:: - In the future a graphical utility might be written to automate common tracing tasks. -``` +:::{note} +In the future a graphical utility might be written to automate common tracing tasks. +::: diff --git a/developer/ux-guidelines.md b/developer/ux-guidelines.md index b7e4622e..f7a42970 100644 --- a/developer/ux-guidelines.md +++ b/developer/ux-guidelines.md @@ -28,7 +28,7 @@ advantage over other menu systems. 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 more efficient to place menus at the top of the window -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. https://dl.acm.org/doi/pdf/10.1145/97243.97277 +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. ## Avoiding hidden menus hamburger icons diff --git a/index.md b/index.md index de79eec2..50294fea 100644 --- a/index.md +++ b/index.md @@ -1,10 +1,10 @@ -```eval_rst -.. image:: https://raw.githubusercontent.com/helloSystem/hello/1d1e69be8a689c5e0a176df821c14f0b49b241a4/branding/hello_variation.svg - :align: center - :width: 300px +```{image} https://raw.githubusercontent.com/helloSystem/hello/1d1e69be8a689c5e0a176df821c14f0b49b241a4/branding/hello_variation.svg +:alt: The helloSystem logo +:width: 300px +:align: center ``` -```eval_rst +```{eval-rst} .. centered:: Willkommen • Welcome • Bienvenue • Benvenuto • Bienvenido • ようこそ • Mabuhay • Tervetuloa • Välkommen • Добро пожаловать • Hoş geldiniz • Bonvenon • 歡迎 ``` @@ -14,50 +14,54 @@ __helloSystem__ is a desktop system for creators with a focus on simplicity, ele ![Screenshot](https://github.com/helloSystem/hello/blob/master/screenshots/20220121-desktop-0.8.png?raw=true) -```eval_rst -.. toctree:: - :maxdepth: 3 - :caption: User Guide - :hidden: - :glob: - - user/getting-started - user/components - user/troubleshooting - user/feedback +```{toctree} +--- +maxdepth: 3 +caption: User Guide +hidden: true +glob: true +--- + +user/getting-started +user/components +user/troubleshooting +user/feedback + ``` -```eval_rst -.. toctree:: - :caption: Developer Guide - :hidden: - :maxdepth: 2 - :glob: - - developer/ux-guidelines - developer/architecture - developer/boot - developer/geom_rowr - developer/graphics - developer/binary-compatibility - developer/applications - developer/application-bundles - developer/menu - developer/filer-context-menus - developer/developer-tools - developer/midi - developer/specifications - developer/contributing - developer/building - developer/monkey-patch - developer/tracing - developer/localization - developer/ports - developer/base - developer/man - developer/rpi - developer/linux - developer/distributions - developer/acknowledgements - developer/contact +```{toctree} +--- +caption: Developer Guide +hidden: true +maxdepth: 2 +glob: true +--- + +developer/ux-guidelines +developer/architecture +developer/boot +developer/geom_rowr +developer/graphics +developer/binary-compatibility +developer/applications +developer/application-bundles +developer/menu +developer/filer-context-menus +developer/developer-tools +developer/midi +developer/specifications +developer/contributing +developer/building +developer/monkey-patch +developer/tracing +developer/localization +developer/ports +developer/base +developer/man +developer/rpi +developer/linux +developer/distributions +developer/acknowledgements +developer/contact + ``` diff --git a/requirements.txt b/requirements.txt index 0225a94b..2741eaf0 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,12 +1,10 @@ wheel -sphinx>=3.3.0 -sphinx_rtd_theme +sphinx>=5.0.0 +sphinx_rtd_theme>=0.5.2 sphinx-autobuild -sphinx_git -#sphinx-reredirects -sphinxext-rediraffe -# will only work once a new release is made after sphinx-rtd-theme 0.5.0 sphinx-last-updated-by-git -recommonmark +myst-parser sphinxcontrib-qthelp -sphinx-markdown-tables +# docutils needs to be pinned for now so that lists work +# See https://github.com/readthedocs/sphinx_rtd_theme/issues/1115 for more information +docutils==0.16 diff --git a/user/components.md b/user/components.md index cc7b88db..6bdf4dc5 100644 --- a/user/components.md +++ b/user/components.md @@ -2,10 +2,12 @@ helloSystem consists of the following key components, each of which are described in this section: -```eval_rst -.. toctree:: - :maxdepth: 2 - :glob: - - components/* -``` + +```{toctree} +--- +maxdepth: 2 +glob: true +--- + +components/* +``` diff --git a/user/components/applications.md b/user/components/applications.md index 74957b11..de577603 100644 --- a/user/components/applications.md +++ b/user/components/applications.md @@ -8,10 +8,11 @@ helloSystem comes with some applications out of the box, and some applications n 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. -```eval_rst -.. toctree:: - :maxdepth: 2 - :glob: +```{toctree} +--- +maxdepth: 2 +glob: true +--- - applications/* +applications/* ``` diff --git a/user/components/preferences.md b/user/components/preferences.md index 792f9d6d..977f4cd3 100644 --- a/user/components/preferences.md +++ b/user/components/preferences.md @@ -2,10 +2,11 @@ helloSystem comes with the following preferences applications, each of which are described in this section: -```eval_rst -.. toctree:: - :maxdepth: 2 - :glob: +```{toctree} +--- +maxdepth: 2 +glob: true +--- - preferences/* -``` +preferences/* +``` diff --git a/user/components/preferences/boot-environments.md b/user/components/preferences/boot-environments.md index 4f3de5f2..cd967f31 100644 --- a/user/components/preferences/boot-environments.md +++ b/user/components/preferences/boot-environments.md @@ -4,15 +4,15 @@ _Boot Environments_ are bootable clones of snapshots of the working system. Boot Other applications may create Boot Environments automatically before performing critical operations such as major operating system upgrades. -``` .. warning:: - Boot Environments by default do not cover all locations, such as `/home` where your personal data is usually stored. -``` +:::{warning} +Boot Environments by default do not cover all locations, such as `/home` where your personal data is usually stored. +::: The __Boot Environments__ preferences application lets you view, create, remove, mount, and boot into Boot Environments. -``` .. note:: - 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. -``` +:::{note} +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. +::: ## Viewing Boot Environments @@ -22,23 +22,23 @@ You will see the available Boot Environments. ## Creating Boot Environments -To create a new Boot Environment, click "New..." and enter a name for the new Boot Environment. +To create a new Boot Environment, click {guilabel}`New...` and enter a name for the new Boot Environment. ## Removing Boot Environments -Select a Boot Environment by clicking on it, and then press "Remove". Note that you cannot remove the currently active Boot Environment. +Select a Boot Environment by clicking on it, and then press {guilabel}`Remove`. Note that you cannot remove the currently active Boot Environment. ## Mounting Boot Environments You can make available, or "mount", existing Boot Environments, e.g., in order to inspect them or to copy files from there. -To do this, select a Boot Environment by clicking on it, and then press "Mount". Note that you cannot mount the currently active Boot Environment since it is already mounted at `/`. +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 `/`. The selected Boot Environment will be mounted, and a Filer window will be opened at the mountpoint of the Boot Environment. ## Booting into a Boot Environment -Activate a Boot Environment by checking its checkbox, and then press "Restart...". The computer will restart into the selected Boot Environment. +Activate a Boot Environment by checking its checkbox, and then press {guilabel}`Restart...`. The computer will restart into the selected Boot Environment. ## More Information diff --git a/user/components/preferences/desktop.md b/user/components/preferences/desktop.md index 39b34e0e..443ce1f0 100644 --- a/user/components/preferences/desktop.md +++ b/user/components/preferences/desktop.md @@ -12,4 +12,4 @@ In this section of the __Desktop__ preferences application, you can select a fon ## Advanced -Under the __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. +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. diff --git a/user/components/preferences/keyboard.md b/user/components/preferences/keyboard.md index 297ed612..bcae23b4 100644 --- a/user/components/preferences/keyboard.md +++ b/user/components/preferences/keyboard.md @@ -1,10 +1,10 @@ # Keyboard -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 ⌘ (command) key. It also lets you disable the Caps Lock key. +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. -``` .. note:: - 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. -``` +:::{note} +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. +::: ## Setting the keyboard layout @@ -12,11 +12,11 @@ Simply click on a language (keyboard layout). The change is effective immediatel ## Selecting a physical key to act as ⌘ (command) -Swapping the keys will result in the key left from the spacebar to act as the ⌘ (command) key (like switchers from the Mac would expect) and therefore is the default. +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. -__If a PC keyboard is attached__, you can select the "Use the Alt key as ⌘" checkbox. This will swap the __Ctrl__ and __Alt__ keys. +__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. -__If an Apple keyboard is attached__, you can select the "Use the ⌘ key for menu shortcuts" checkbox. This will swap the __alt ⌥__ and __cmd ⌘__ keys. +__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. If you prefer the keys not be swapped, simply uncheck the respective checkbox. The change is effective immediately. diff --git a/user/components/preferences/sharing.md b/user/components/preferences/sharing.md index 1fabaa77..ecca57ad 100644 --- a/user/components/preferences/sharing.md +++ b/user/components/preferences/sharing.md @@ -10,11 +10,11 @@ The __Computer Name__ (hostname) is displayed. You can change it. Changes in the ## Remote Login -Check the __Remote Login__ checkbox to make your computer accessible over ssh. +Check the {guilabel}`Remote Login` checkbox to make your computer accessible over ssh. ## Screen Sharing -Check the __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 __Screen Sharing__ checkbox will automatically be unchecked when the computer is restarted or after a connection has been made and has ended. +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. ## Accessing the screen of remote computers @@ -23,23 +23,24 @@ Check the __Screen Sharing__ checkbox to make the screen of your computer access 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. In SSVNC please do: -* Under "VNC Host_Display" please enter: :0 -* Options... -> Check the "Use SSH" box and the "Unix Username & Password" box -* Under "Unix Username" enter the username you have set when you installed helloSystem -* Under "Unix Password" enter the password you have set when you installed helloSystem + +* Under {guilabel}`VNC Host_Display` please enter: `:0` +* {guilabel}`Options...` -> Check the {guilabel}`Use SSH` box and the {guilabel}`Unix Username & Password` box +* Under {guilabel}`Unix Username` enter the username you have set when you installed helloSystem +* Under {guilabel}`Unix Password` enter the password you have set when you installed helloSystem ## Accessing the screen of a remote computer that has Remote Login enabled 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: -``` -ssh -t -L 5900:localhost:5900 user@FreeBSD.local. 'x11vnc -display :0 -auth /home/user/.Xauthority -once -localhost' +```console +$ ssh -t -L 5900:localhost:5900 user@FreeBSD.local. 'x11vnc -display :0 -auth /home/user/.Xauthority -once -localhost' ``` Log into the remote computer. Then start the Remote Desktop client as follows: -``` -ssvncviewer localhost +```console +$ ssvncviewer localhost ``` You should now be able to see and operate the screen. diff --git a/user/components/preferences/shortcuts.md b/user/components/preferences/shortcuts.md index 9c521597..2c0d2b18 100644 --- a/user/components/preferences/shortcuts.md +++ b/user/components/preferences/shortcuts.md @@ -1,47 +1,47 @@ # Shortcut Keys -The __Shortcut Keys__ preferences application lets you view and edit system-wide keyboard shortcuts. +The {guilabel}`Shortcut Keys` preferences application lets you view and edit system-wide keyboard shortcuts. -``` .. note:: - The left Ctrl and Alt keys are swapped in helloSystem by default to make shortcuts feel welcoming to switchers coming from the Mac. -``` +:::{note} +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. +::: 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). -``` .. note:: - 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. -``` +:::{note} +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. +::: ## The ⌘ key -The ⌘ key, also known as Command, is the key left to the spacebar on helloSystem, unless you have configured your system differently. +The {kbd}`⌘` key, also known as __Command__, is the key left to the spacebar on helloSystem, unless you have configured your system differently. -``` .. note:: - Non-native software may refer to the Command key as "Ctrl". This is a known cosmetic issue. -``` +:::{note} +Non-native software may refer to the Command key as "Ctrl". This is a known cosmetic issue. +::: ## Default shortcuts -Open the __Shortcut Keys__ preferences application to view the default system-wide shortcuts. +Open the {guilabel}`Shortcut Keys` preferences application to view the default system-wide shortcuts. Notable default shortcuts include: -* Press `⌘Space` to __search in the Menu__ (e.g., to launch applications or to execute commands in the frontmost application) -* Press `Ctrl⌘Esc` and click on an application window to __forcefully quit an application__ that is malfunctioning -* Press `⌘⇧3` or the __PrtScn__ key on your keyboard to __take a screenshot__ -* Press `⌘⇧H` to go to the Home folder -* Press `⌘⇧A` to go to the Applications folder -* Press `⌘⇧U` to go to the Utilities folder -* Press `Ctrl⌘T` to open a Terminal -* Press `Ctrl⌘I` to open the internet browser +* Press {kbd}`⌘` + {kbd}`Space` to __search in the Menu__ (e.g., to launch applications or to execute commands in the frontmost application) +* Press {kbd}`Ctrl` + {kbd}`⌘` + {kbd}`Esc` and click on an application window to __forcefully quit an application__ that is malfunctioning +* Press {kbd}`⌘` + {kbd}`⇧` + {kbd}`3` or the {kbd}`PrtScn` key on your keyboard to __take a screenshot__ +* Press {kbd}`⌘` + {kbd}`⇧` + {kbd}`H` to go to the Home folder +* Press {kbd}`⌘` + {kbd}`⇧` + {kbd}`A` to go to the Applications folder +* Press {kbd}`⌘` + {kbd}`⇧` + {kbd}`U` to go to the Utilities folder +* Press {kbd}`Ctrl` + {kbd}`⌘` + {kbd}`T` to open a Terminal +* Press {kbd}`Ctrl` + {kbd}`⌘` + {kbd}`I` to open the internet browser This list is not exhaustive. ## Viewing shortcuts -For a complete list of system-wide shortcuts, please open the __Shortcut Keys__ preferences application to view the default shortcuts. +For a complete list of system-wide shortcuts, please open the {guilabel}`Shortcut Keys` preferences application to view the default shortcuts. ## Editing shortcuts -Use the buttons in the __Shortcut Keys__ preferences application to add, remove, and modify system-wide shortcuts. +Use the buttons in the {guilabel}`Shortcut Keys` preferences application to add, remove, and modify system-wide shortcuts. diff --git a/user/components/preferences/wireless-networks.md b/user/components/preferences/wireless-networks.md index 7cf4a7ea..1f94af73 100644 --- a/user/components/preferences/wireless-networks.md +++ b/user/components/preferences/wireless-networks.md @@ -1,9 +1,9 @@ # Wireless Networks -The __Wireless Networks__ preferences application lets you connect to wireless local area networks (WLANs). +The {guilabel}`Wireless Networks` preferences application lets you connect to wireless local area networks (WLANs). It is possible to use more than one wireless network card. -``` .. note:: - Please consider using the Hardware Probe utility in case your network card is not detected by the Wireless Networks preferences application. -``` +:::{note} +Please consider using the Hardware Probe utility in case your network card is not detected by the Wireless Networks preferences application. +::: diff --git a/user/components/system.md b/user/components/system.md index a54d3435..e85bcbbd 100644 --- a/user/components/system.md +++ b/user/components/system.md @@ -2,10 +2,11 @@ helloSystem comes with the following system components, each of which are described in this section: -```eval_rst -.. toctree:: - :maxdepth: 2 - :glob: +```{toctree} +--- +maxdepth: 2 +glob: true +--- - system/* +system/* ``` diff --git a/user/components/system/launch.md b/user/components/system/launch.md index 83590ace..fcf8cbbe 100644 --- a/user/components/system/launch.md +++ b/user/components/system/launch.md @@ -1,43 +1,39 @@ - # launch +# launch - ```eval_rst - .. epigraph:: +```{epigraph} +"It’s not just what it looks like and feels like. Design is how it works." - "It’s not just what it looks like and feels like. Design is how it works." - - -- Steve Jobs +-- Steve Jobs ``` - The `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 `launch` command is invoked to actually launch the application. - - ```eval_rst - .. hint:: - - As an end user who is using the graphical user interface exclusively, you will not need to interact with the `launch` command directly and can skip this section. - ``` - - ## Background - - 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. - - 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 `launch` command to launch graphical applications. This has the following advantages: - - * You do not need to know the path to the application to be launched, even if the application is not on the `$PATH` - * 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)__ - * If something goes wrong and the application cannot be launched, then a graphical error message will be shown on the screen - - ![Graphical error message if something goes wrong](https://pbs.twimg.com/media/EoLKXl7WEAAWCtQ?format=png) +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. - ## Using the `launch` command +:::{hint} +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. +::: - Whenever possible, graphical applications should be launched through the `launch` command on helloSystem. +## Background - There are several ways in which the `launch` command can be invoked: - - * `launch /Applications/Filer.app` - * `launch Filer.app` - * `launch Filer` +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. +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: + +* You do not need to know the path to the application to be launched, even if the application is not on the `$PATH` +* 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)__ +* If something goes wrong and the application cannot be launched, then a graphical error message will be shown on the screen + +![Graphical error message if something goes wrong](https://pbs.twimg.com/media/EoLKXl7WEAAWCtQ?format=png) + +## Using the launch command + +Whenever possible, graphical applications should be launched through the {command}`launch` command on helloSystem. + +There are several ways in which the {command}`launch` command can be invoked: + +* `launch /Applications/Filer.app` +* `launch Filer.app` +* `launch Filer` + Note that capitalization can have subtle effects: * `launch audacity` launches `audacity` from the `$PATH` if it exists anywhere on the `$PATH` diff --git a/user/components/system/menu.md b/user/components/system/menu.md index 912f2860..dbdcad70 100644 --- a/user/components/system/menu.md +++ b/user/components/system/menu.md @@ -25,7 +25,7 @@ Select "Unhide all" to get all windows back on screen. Select an application from "Applications", "Utilities", or "Preferences" in the "Applications" menu. -A quicker way to launch an application is to press Alt+Space, enter a few characters of the application name, select one of the matches from the list, and press the Enter key. +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. ## Shutting down @@ -33,7 +33,7 @@ To shut down your computer, select "Log Out" from the "System" menu, then click ## Searching in application menus -Click on "Search" in the menu bar, or press __Alt+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. If only one choice remains left as you are typing, the remaining entry automatically gets selected. +Click on "Search" in the menu bar, or press {kbd}`Alt+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. If only one choice remains left as you are typing, the remaining entry automatically gets selected. ## Date and time diff --git a/user/components/utilities.md b/user/components/utilities.md index 1b1a8de6..03270a8d 100644 --- a/user/components/utilities.md +++ b/user/components/utilities.md @@ -2,10 +2,11 @@ helloSystem comes with the following utilities, each of which are described in this section: -```eval_rst -.. toctree:: - :maxdepth: 2 - :glob: +```{toctree} +--- +maxdepth: 2 +glob: true +--- - utilities/* +utilities/* ``` diff --git a/user/components/utilities/create-live-media.md b/user/components/utilities/create-live-media.md index dbbd0d26..29173a18 100644 --- a/user/components/utilities/create-live-media.md +++ b/user/components/utilities/create-live-media.md @@ -15,20 +15,20 @@ In order to create a Live medium, you need * A fast internet connection (a typical download is around 2 GiB) * 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. -``` .. note:: - The **Create Live Media** utility cannot be used on other operating systems such as Windows, Linux, or macOS. - - 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/). -``` +:::{note} +The **Create Live Media** utility cannot be used on other operating systems such as Windows, Linux, or macOS. + +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/). +::: ## Downloading and writing Live Media 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. -``` .. warning:: - 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. - - This operation cannot be undone. -``` +:::{warning} +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. + +This operation cannot be undone. +::: 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. diff --git a/user/components/utilities/hardware-probe.md b/user/components/utilities/hardware-probe.md index af91839f..c394d810 100644 --- a/user/components/utilities/hardware-probe.md +++ b/user/components/utilities/hardware-probe.md @@ -16,11 +16,11 @@ Private information (including the username, machine's hostname, IP addresses, M 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. -``` .. note:: - By using this utility to upload your hardware probe, you agree that information about your hardware will be uploaded to a publicly visible database. +:::{note} +By using this utility to upload your hardware probe, you agree that information about your hardware will be uploaded to a publicly visible database. - Do not use this utility if you do not agree with this. -``` +Do not use this utility if you do not agree with this. +::: 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. diff --git a/user/components/utilities/install.md b/user/components/utilities/install.md index 67d076f6..24f7f9af 100644 --- a/user/components/utilities/install.md +++ b/user/components/utilities/install.md @@ -4,9 +4,9 @@ Once you have tried out helloSystem from the live medium, you may want to instal The __Install FreeBSD__ utility lets you install helloSystem on your computer from a running Live system. -``` .. note:: - The utility is called **Install FreeBSD** to signify that helloSystem contains a largely unmodified FreeBSD core operating system. It might be renamed "Install helloSystem" in the future. -``` +:::{note} +The utility is called **Install FreeBSD** to signify that helloSystem contains a largely unmodified FreeBSD core operating system. It might be renamed "Install helloSystem" in the future. +::: ![Install FreeBSD](https://user-images.githubusercontent.com/2480569/93003377-7d77c480-f53e-11ea-9e2d-aed1b41a17df.png) @@ -24,11 +24,11 @@ Start your computer from a helloSystem Live Medium. Open the __Install FreeBSD__ The installer starts by presenting a summary of FreeBSD. 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. -``` .. warning:: - The **Install FreeBSD** 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. +:::{warning} +The **Install FreeBSD** 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. - This operation cannot be undone. -``` +This operation cannot be undone. +::: If you are really sure that you have selected the correct device, click "Continue". diff --git a/user/components/utilities/remote-assistance.md b/user/components/utilities/remote-assistance.md index d14c9dab..87e3c97f 100644 --- a/user/components/utilities/remote-assistance.md +++ b/user/components/utilities/remote-assistance.md @@ -2,9 +2,9 @@ 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. -``` .. warning:: - 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. -``` +:::{warning} +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. +::: ## Receiving Remote Assistance diff --git a/user/components/utilities/update.md b/user/components/utilities/update.md index 5d5e429b..68baa26d 100644 --- a/user/components/utilities/update.md +++ b/user/components/utilities/update.md @@ -2,9 +2,9 @@ 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. -``` .. note:: - 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. -``` +:::{note} +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. +::: This utility * 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 diff --git a/user/getting-started.md b/user/getting-started.md index 27a320d6..85f0337a 100644 --- a/user/getting-started.md +++ b/user/getting-started.md @@ -23,8 +23,9 @@ The **helloSystem 0.8.0** ISO image is available for download [here](https://git Experimental and pre-release images are available for download [here](https://github.com/helloSystem/ISO/releases). -> :warning: **Important**
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. - +:::{important} +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. +::: ## Creating Live Media @@ -34,8 +35,8 @@ helloSystem comes with a __Create Live Media__ utility that allows to write ISO If you are not running helloSystem yet or would like to use the command line, the following command should work on all BSD flavors: -``` -sudo dd if= of=/dev/daX bs=4m status=progress +```console +$ sudo dd if= of=/dev/daX bs=4m status=progress ``` On GNU-style systems (e.g., most Linux distributions), `status=progress` does not work and can be left away. @@ -81,18 +82,16 @@ Detailed information on #FreeBSD wireless network card compatibility is availabl ## Virtualization environments -> :warning: **Note**:
We recommend running helloSystem on real hardware ("bare metal") if possible. This should give you the best possible performance and hardware support. +:::{note} +We recommend running helloSystem on real hardware ("bare metal") if possible. This should give you the best possible performance and hardware support. +::: Users have reported success in running helloSystem in the following virtualization environments: * VirtualBox host (on FreeBSD and on macOS), known to work in BIOS and EFI modes - * VMware Workstation works in BIOS and EFI modes (see below) - * 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 - * Parallels host, reported to work in EFI mode (see below) - * Proxmox VE Please note: @@ -109,7 +108,7 @@ Please report back about the results on your virtualization environment. Create an 8 GiB (or larger) `hello.img` image file on which you can install the system: -``` +```console $ pwd /home/user $ mkdir -p .qemu/hello @@ -118,8 +117,8 @@ $ fallocate -l $(( 8*1024*1024*1024 )) .qemu/hello/hello.img Then, boot helloSystem: -``` -qemu-system-x86_64 -machine type=q35,accel=kvm \ +```console +$ qemu-system-x86_64 -machine type=q35,accel=kvm \ -enable-kvm -cpu host -smp 2 -m 4096 \ -device virtio-net,netdev=vmnic -netdev user,id=vmnic,hostfwd=tcp::5222-:22 \ -vga std -soundhw hda -no-quit \ @@ -144,7 +143,7 @@ To boot/install hello in UEFI mode, first install [OVMF Open Virtual Machine Fir Then add these two `qemu-system-x86_64` options: -``` +```text -bios /usr/share/edk2/ovmf/OVMF_CODE.fd \ -smbios type=0,vendor=0vendor,version=0version,date=0date,release=0.0,uefi=on \ ``` @@ -173,11 +172,15 @@ To set resolution, press F2 at boot to access OVMF settings. Select 'Device Mana ### VMware Workstation Tested on VMware Workstation 16.2.1 -> :warning: **Installation Issue**
For best results while installing, please set your CPU to 1 socket, and no more than 4 cores.
After installation, you can set the CPU socket and core count to your desire. +:::{admonition} Installation issue +:class: warning + +For best results while installing, please set your CPU to 1 socket, and no more than 4 cores + +After installation, you can set the CPU socket and core count to your desire. +::: * Memory: 4GB * Processors: 4 (1 socket, 4 cores) * Hard Disk: At least 8GB * Guest Operating System Version: FreeBSD 12 64-bit - - diff --git a/user/troubleshooting.md b/user/troubleshooting.md index 5170eb4e..1227b09a 100644 --- a/user/troubleshooting.md +++ b/user/troubleshooting.md @@ -6,7 +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. -If – after five minutes – you're reluctant to stop the computer, you can occasionally [key 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. +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. * Please restart the computer. If normal use of the power button is not effective, press and hold. * 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. @@ -16,7 +16,7 @@ If – after five minutes – you're reluctant to stop the computer, you can occ This means that Xorg has been started but for some reason the login manager `slim` or the helloDesktop startup script `start-hello` cannot run. * Boot in verbose mode -* Press Ctrl+Alt+F2 +* Press {kbd}`Ctrl+Alt+F2` * Log in * `sudo killall Xorg` * `sudo service dbus restart` @@ -38,15 +38,15 @@ If this does not work: 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 -``` -LD_DEBUG=libs firefox 2>&1 | grep -i menu +```console +$ LD_DEBUG=libs firefox 2>&1 | grep -i menu ``` Or, if we are interested in which activities with "menu" in their name `firefox` is doing, we can run -``` -sudo sysctl security.bsd.unprivileged_proc_debug=1 -truss firefox 2>&1 | grep -e menu +```console +$ sudo sysctl security.bsd.unprivileged_proc_debug=1 +$ truss firefox 2>&1 | grep -e menu ``` ## Other issues