Skip to content

Commit

Permalink
chore: migrate to myst syntax (#48)
Browse files Browse the repository at this point in the history 
* chore: migrate to myst syntax

* remove unnecessary formatting from header

* Update missing admonitions

* Fix typo

* Update dependencies in build script
  • Loading branch information
@Sporiff
Sporiff authored Feb 6, 2023
1 parent a490267 commit 0e46574
Show file tree
Hide file tree
Showing 46 changed files with 901 additions and 901 deletions.
3 changes: 1 addition & 2 deletions buildDocs.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 #
Expand Down
24 changes: 5 additions & 19 deletions conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,6 @@
# import sys
# sys.path.insert(0, os.path.abspath('.'))

import recommonmark
from recommonmark.transform import AutoStructify


# -- Project information -----------------------------------------------------

Expand All @@ -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'
Expand Down Expand Up @@ -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)
12 changes: 6 additions & 6 deletions developer/application-bundles.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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)
Expand Down Expand Up @@ -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`.
Expand Down
2 changes: 1 addition & 1 deletion developer/applications.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
12 changes: 6 additions & 6 deletions developer/architecture.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,22 +32,22 @@ 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

A very simple IPC mechanism should be introduced for the desktop components to talk to each other. A lightweight, standard publish/subscribe mechanism should be identified; _possibly_ something like MQTT (which would have the added benefit of allowing for network-wide communication). In the meantime, the use of D-Bus as a legacy technology may be acceptable (even though it is considered obscure, convoluted, and closely linked with various other Red Hat technologies.)

### Applications

Applications must not need to be installed. Simply downloading them, attaching an external drive containing them, or connecting to a network share containing them must be sufficient. Multiple versions of the same application must be able to co-exist. The `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.

Expand Down
37 changes: 19 additions & 18 deletions developer/base.md
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
<https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=251025> can be fixed by changing a few lines in

https://github.com/freebsd/freebsd-src/blob/main/usr.sbin/efivar/efivar.c
<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 <http://ftp.freebsd.org/pub/FreeBSD/releases/amd64/12.2-RELEASE/> (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
```
53 changes: 26 additions & 27 deletions developer/binary-compatibility.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

* <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/)
Loading

0 comments on commit 0e46574

Please sign in to comment.