summaryrefslogtreecommitdiffhomepage
path: root/mutiny.7.adoc
blob: 8436ccec61930e36963ab34dcec5e9ad4a1fa655 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
= mutiny(7)

:description: A BSD-inspired Linux system and research project, aiming to be a testbed for \
              interesting system design, forward thinking design choices, minimalism, and fun \
              computing.
:pp: ++

== Name

mutiny - BSD-inspired Linux system and research project aiming to be a testbed for interesting
system design, forward thinking design choices, minimalism, and fun computing

== Synopsis

Mutiny is a project aiming to deliver a Linux distribution that prioritizes a consistent,
interesting, and fun to use system. Influenced heavily by BSD system design, minimalist software,
and an interest in forward-thinking system design, Mutiny aims to explore alternatives to the
hegemony that makes up most Linux distributions.

ifdef::backend-html5[]
image::logo.svg[Mutiny logo]

Mutiny is young! If you find the ideas here interesting, please reach out at
irc://irc.freenode.net/#mutiny.

There's a set of https://git.mutiny.red/mutiny[git repositories]. No bootable system yet, this OS
mostly exists as a pile of documents and some broken chroots for now.

This is the main document, here's a few other documents written currently:

* A design document about <<praxis.7.adoc#,praxis>>, the package manager.
* A longer but unfinished document about the package API, <<theory.5.adoc#,theory>>.
* A <<software.7.adoc#,running list of software>> that might be of interest for Mutiny.

endif::[]

== Goals

*Consistency*::
    Linux systems have suffered from a large amount of inconsistencies in maintenance and style.
    This is part due to the bazaar model of development, but it doesn't have to be this way.
    Software should be bent to conform, and users should come to expect things are going to be a
    certain way on a *Mutiny* system.

*Uniqueness*::
    There are advantages that come with many sorts of distributions acting all alike. But, if you
    aren't a fan of the similarities, it means there's not much of an alternative for you to look
    out for. We don't all want a Windows, or a GNOME, or a Mac, and that's okay, just like the
    people that do. Keeping in line with the testbed attitude, *Mutiny* will always try to make a
    unique system that people can learn to appreciate for the differences.

*Alternatives*::
    In the Linux world there is often an acceptance that some of the system just
    sucks, but that's just what we're stuck with. And that's reasonable in some cases where
    alternatives don't exist.
    However, *Mutiny* should aim to thoroughly explore alternatives when they do exist.

*Documentation*::
    The system should be thoroughly documented so that you never need to
    reference external websites in order to learn about it. Documentation should be consistent,
    too. On *Mutiny*, all documentation should be accessible through *man* or _/share/doc_.

=== Documentation

The state of system administration nowadays can be very fragmented. Most people just search for the
documentation online nowadays, finding the manuals to be lacking, or just too archaic.

However this is rarely a problem with *BSD systems. This is because BSD systems, historically, have
put more emphasis on good documentation of their systems. Every single aspect of the kernel's
internals, drivers, quirks, etc., is documented in a manpage.

On a large scale, this unity in the system is what Mutiny is striving for. Linux systems have had a
tendency to be disjointed at times, as the model which the system is developed in doesn't usually
correspond to the stewardship that comes with the tightly-managed attitude of something like
OpenBSD.

Manual pages will be required for any package that installs a program to _/bin_, and in all files in
_/etc_ will also require manual pages to exist for them.

=== Standards adherence

:filesystem-hierarchy-standard:     http://refspecs.linuxfoundation.org/FHS_3.0/fhs-3.0.html
:file-hierarchy:                    https://www.freedesktop.org/software/systemd/man/file-hierarchy.html
:xdg-base-directory-specification:  https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html

Mutiny should aim to adhere to standards whenever it is possible, and enforce those standards
on all software that the system uses. When a standard isn't good, or we think it is badly
designed, we should aim to supersede it with a defined standard of our own. The prime example
of a bad standard being replaced in Mutiny is the <<Filesystem layout>>, which supersedes the
{filesystem-hierarchy-standard}[Filesystem Hierarchy Standard] and systemd's
{file-hierarchy}[file-hierarchy].

Good examples of standards we want to follow would be standards like the
{xdg-base-directory-specification}[XDG Base Directory Specification].

== Prior art

* https://www.exherbo.org[Exherbo Linux] - My former distribution of choice, helped me realize the
  potential of source-based distributions; ultimately our interests diverged.
* https://www.openbsd.org[OpenBSD]
* http://sabotage.tech[Sabotage Linux]
* https://alpinelinux.org[Alpine Linux]
* https://voidlinux.eu[Void Linux]
* https://github.com/michaelforney/oasis[oasis]
* https://github.com/kissx/kiss[kiss linux]

== System

:github:    https://github.com
:skarnet:   https://skarnet.org/software
:gnu:       https://www.gnu.org/software
:oil-shell: https://www.oilshell.org

.Software
* Mutiny
    ** <<praxis.7.adoc#,`praxis`>> - a source-based package manager
    ** `synonym` - a utility for managing alternatives
    ** `commune` - utilities for working with the `s6` and `s6-rc` state manager/supervisor
        *** `commune-snooze` - manages scheduled jobs at the system and user scope
        *** `commune-user` - manages the user’s services and states (cf. `systemd --user`)
        *** `commune-xinit` - manages the user’s Xorg session

* Base
    ** Kernel: https://www.kernel.org/[Linux], long-term releases only
    ** Standard C library: https://www.musl-libc.org[`musl`]
    ** Core system utilities: http://www.landley.net/toybox/[`toybox`]
        *** https://www.busybox.net[`busybox`] to fill in the cracks, temporarily
    ** Default shell: {github}/ibara/oksh[OpenBSD `ksh`]
        *** A long-term interest is switching to the {oil-shell}[Oil shell] once it is fully
            functional.
        *** {github}/emersion/mrsh[`mrsh`] may also be looked into, though it lacks arrays and
            likely won't ever have them since they aren't part of POSIX.
    ** Init system: {skarnet}/s6[`s6`], {skarnet}/s6-rc[`s6-rc`]
    ** Job scheduling: {github}/leahneukirchen/snooze[`snooze`]
    ** System automation: {skarnet}/execline[`execline`]
        *** System-management scripts that are not invoked by a user will be written in execline
            whenever possible.
    ** Device handling, firmware loading: {skarnet}/mdevd[`mdevd`]
    ** SSL library: https://www.libressl.org[`libressl`]
    ** Manual page reader: https://mandoc.bsd.lv[`mandoc`]

* Toolchain
    ** https://llvm.org[LLVM]
        *** https://clang.llvm.org/[`clang`]
        *** https://libcxx.llvm.org[`libc{pp}`]
            **** https://libcxxabi.llvm.org[`libc{pp}abi`]
        *** https://lld.llvm.org[`lld`]
    ** https://git.2f30.org/fortify-headers[`fortify-headers`]
    ** https://github.com/sabotage-linux/gettext-tiny[`gettext-tiny`]
    ** https://invisible-island.net/byacc/byacc.html[`byacc`]

.Software being avoided
https://www.freedesktop.org/wiki/Software/dbus[dbus]::
    I'm interested in seeking out alternatives to it for a few reasons.

    . There's only two real implementations of it: the reference implementation, which is what most
      people use and apparently has enough performances issues that people are working to shove it
      into the kernel instead of userspace, and https://github.com/bus1/dbus-broker[dbus-broker],
      which seems to have some level of dependency on systemd. While it might not necessarily be the
      case, this to me signifies some level of complexity in implementation that I'm not interested
      in accepting as the norm, and possibly as a system component if enough things want to use it.
    . There seems to be some good criticism to be had that it is reinventing the wheel.
    . I think that some of its features, such as service activation, have no place in a system bus.

    . All this aside: it's still required if you use Bluetooth on Linux.

    . Alternative: {skarnet}/skabus[skabus]. Heavily a work in progress, but it looks interesting.
      For now though, the plan is just to stay away from dbus as much as possible.

https://www.freedesktop.org/wiki/Software/PulseAudio[PulseAudio]::
    . A bit worryingly complex.
    . The main appeal of it is in multiplexing sound sources on one sound card. This can already be
      done with ALSA, it's just not pretty to configure.
    . The alternative: http://www.sndio.org[sndio]. It's from OpenBSD, it seems to be a lot simpler,
      and fits in well with the philosophy we're going for because of this.

Nonessential but otherwise interesting software that would be a good fit to the philosophy can be
found on the <<software.adoc#,software page>>.

=== Filesystem layout

In the Mutiny layout, there are a few goals:

* Accomodate some common paths; `#!/bin/sh`, etc.
* Embrace the _good_ innovations that have occurred, like `/run` and the `/sbin`+`/bin` merge.
* Remove redundancy. No more `/media` or `/usr`, `/tmp` points to `/run/tmp`.

```
/                           - The root, and root user's home directory.
├── bin                     - System-managed binary files.
├── dev                     - Device files. (devtmpfs)
├── etc                     - System-localized configuration.
├── home                    - User files.
├── include                 - System-managed header files.
├── lib                     - System-managed library files.
├── local
│   ├── bin                 - User-managed binary files.
│   ├── include             - User-managed header files.
│   ├── lib                 - User-managed library files.
│   └── share               - User managed resource files.
│       └── man             - User-managed manual pages.
│
├── mnt                     - Mounted devices and mountpoints.
├── proc                    - Process information. (procfs)
├── run                     - Runtime files. (tmpfs, directory structure created at boot)
│   ├── tmp                 - Temporary files. (cleared at boot)
│   └── user                - User runtime files.
│       └── 1000            - User's `$XDG_RUNTIME_DIR`. (created at login)
│           └── commune     - User's supervision trees, maintained by `commune` scopes.
│               ├── snooze  - Corresponds to the running supervision tree for user's jobs.
│               │             Maintained by `commune-snooze`.
│               ├── user    - Corresponds to the running supervision tree for the user.
│               │             Maintained by `commune-user`.
│               └── xinit   - Corresponds to the running supervision tree for the user's Xorg
│                             session. Maintained by `commune-xinit`.
│
├── sbin                    - Symbolic link to `bin`.
├── share                   - Managed resource files.
│   └── man                 - System manual pages.
│
├── srv                     - Service directories. (git-daemon, httpd)
│   ├── git
│   └── http
│
├── sys                     - System/kernel information. (sysfs)
├── tmp                     - Symbolic link to `run/tmp`.
├── usr                     - Symbolic link to `.`.
└── var                     - Persistent system data.
    ├── cache               - Cache for system programs.
    │   └── praxis
    │       └── distfiles   - Downloaded source for packages.
    │
    ├── lib                 - Log files for system programs.
    ├── log                 - Databases and other data for system programs.
    ├── run                 - Symbolic link to `../run`.
    └── tmp                 - Persistent yet temporary files, not cleared at boot.
```

At one point, there was an intent to support cross-compilation, akin to Exherbo's multiarch design.
This has been removed due to a lack of necessity and ultimately, little gain for a lot of pain to
take on.

== Package design

* Reasonable command line interface
* Run (inexpensive) tests by default
* Libraries
    ** See: Gentoo's eclasses, Exherbo's exlibs
* Useful metadata
    ** Build dependencies vs. runtime dependencies
    ** Licenses
    ** Links to documentation

== Notes

(ideally these will disappear and turn into their own sections or pages or what have you)

=== On languages and internationalization

The insistance of English being "the default language of computing" as a rationale to justify
not replacing `gettext` is rather stupid, when not a bit xenophobic. Asserting default languages
of entire fields has real world implications when it gets down to the people using them. There's a
really interesting tendency in the Unix development crowds that have minimalist design tendencies
to just ignore this.

Mutiny packages should allow for options to only install whatever languages are going to be used.
We _can_ set `en_US` as the default language that is enabled in packages, but only if we are going
to provide complete support to those who speak other languages. There's an obvious question here
as to documentation and support through things like IRC though, and I'm only one person.

=== Documentation

A goal should be to ensure that most documentation is `mdoc` format. `s6` is a notable example of a
project that doesn't currently have manpages, though I believe that's something many people in the
community have been wanting.

There's a few tools written by the main `mandoc` dev that convert other formats to mdoc, they might
be worth looking at.

* https://mandoc.bsd.lv/docbook2mdoc[`docbook2mdoc`]
* https://mandoc.bsd.lv/pod2mdoc[`pod2mdoc`]
* https://mandoc.bsd.lv/texi2mdoc[`texi2mdoc`]

=== s6 based stuff

In Mutiny, a goal should be to have the same software powering many scopes of the system. This
promotes the ability to have an intimate familiarity with the foundation of your system, and thus an
easier introduction to administrating it and doing cool stuff with it. A really good point in which
this can be carried out is in `s6` and `s6-rc`.

I have a work in progress implementation of doing this at the `xinit` level, since it's definitely
possible to do a supervisor as your session manager for Xorg sessions. Furthermore, this should be
able to be carried up to the login level. (call it `commune-user`) This could mean user services
for users on the system, akin to systemd's user scope...

=== Software contortions

* XDG contortions
    ** https://wiki.archlinux.org/index.php/XDG_Base_Directory#Partial[lots of software can be told to use XDG if you just give them the right variables]
    ** should software distributed by us be patched to use XDG?

include::footer.adoc[]