review up to Custom tools

content/baguette/index.md

@@ -1,5 +1,5 @@
 +++
-title = "Baguette - OS, tools and stuff"
+title = "BaguetteOS, tools and stuff"
 
 paginate_by = 5
 +++
@@ -19,21 +19,22 @@ BaguetteOS status: Work In Progress.
 A beta will be available circa mid-2020 for advanced users.
 End of the year for simple users.
 
-<red>Warning:</red> this documentation is currently mostly oriented toward advanced unix users.
+<red>Warning:</red> this documentation is currently mostly oriented towards advanced unix users.
 We provide insights on system administration, expose our ideas and point of view.
 Documentation for simple users will be split in another page, soon.
 
 ## Objectives, for simple users
 
-BaguetteOS aims at provide a simple unix-like system, with an **unified web interface**.
+BaguetteOS aims at providing a simple unix-like system, with an **unified web interface**.
 
 **No command-line required for simple users.** *let users be just users*<br />
-Simplicity should not only comes from an interface, but be inherent to the whole system.
+Simplicity should not only come from an interface, but be inherent to the whole system.
 If the OS is simple, there is no need to hack it.
 
 **Unified interface is better than features.**<br />
-We will provide the basic features then build up.
-We do not want a patchwork of very different software, each of them having their own particularities.
+Our web interface will directly provide the basic features such as mail, instant messaging, etc.
+The list of features covered by our interface will grow-up continuously. 
+We do not want a patchwork of very different software, each of them having its own particularities.
 
 **Online services.** *day-to-day use*<br />
 The web interface should cover online services, providing an unified experience for main usages: mails, calendar, instant messaging, personal website, file sharing, etc.
@@ -43,8 +44,8 @@ The web interface should handle basic system and network configurations, such as
 
 **Well-known, reliable software.** *for real*<br />
 BaguetteOS relies on robust and independent software.
-At no point the user should be forced to reinstall, a misconfiguration has to be easily fixed.
-Static compilation for system tools *(at least)*: there is almost no way to get a broken system with an update (yes, *almost*, people are creative these days).
+At no point the user should be forced to reinstall, a misconfiguration has to be easily fixable.
+We use static compilation for *(at least)* system tools: there is almost no chance an update break the system (yes, *almost*, people are creative these days).
 
 **Hardware support.** *new or old, fast or slow, it doesn't matter*<br />
 We provide support for RPi and other small cards: if our kernel runs on it, it has to work.
@@ -53,31 +54,30 @@ Minimal hardware requirement should be around 100 MB RAM, 50 MB disk.
 **Documentation.** *simple, reliable, useful, all-in-one-place*<br />
 Similar to the OpenBSD FAQ: updated, complete, concise and well-written.
 
-**Constrained devices use case.** *wanna try what small systems can do?*<br />
-By default, we try to provide the smallest memory footprint: we do not ship manuals, nor runtime libraries when not required.
+**Constrained devices use case.** *wanna see what small systems can do?*<br />
+By default, we try to provide the smallest memory footprint: we do not provide manuals nor runtime libraries when not required.
 Our programs will never require you to download development libraries, nor alternative package managers.
-The kernel is compiled with size in mind, as our choice of tools.
+We choose all of our tools with size in mind.
 As a result, our system can be installed quickly even on slow machines.
 
 ## Objectives, for advanced users
 
 **A knowable OS.** *simplicity at (almost) all cost*<br />
-Any interested user should be able understand the role of every part of the base system: no compromise.
+Any interested user should be able to understand the role of every part of the base system: no compromise.
 This means having a very small and consistent set of tools, easy to learn, easy to remember.
 
 **Basic system and network management.** *with the simplest tools ever*<br />
 We provide a web interface that should handle basic system and network configurations, such as adding users, firewall management, dhcp, DNS, backups, etc.
-CLI tools are available to manage your services, they are design to be simple, consistent and reliable.
+CLI tools are available to manage services, they are designed to be simple, consistent and reliable.
 
-**Officially supported and documented services.** *so you are sure to get them working*<br />
+**Officially supported services.** *so you are sure to get them working*<br />
 We use some services for our own personal usage, so we will provide support for them.
-For instance: gitea, postgresql, a building plateform and a continuous integration tool, etc.
+For instance: gitea, postgresql, etc.
 
 **One need, one tool.** *this time for real*<br />
 Installing an application or a library is done by [package][package].
 Other methods are not supported **and the base system will never require them**.
 We avoid to rely on `pip`, `cpanm`, or other third party package manager and dependency tree.
-More on that in the [technical section](#technical-choices).
 
 Starting, stopping, or configuring a service is done by [service][service].
 This program alone is used to manage services on the OS.
@@ -89,57 +89,62 @@ Manual configuration is the last option.
 [Slotting](#slotting) by default helps to install many programs, even with peculiar library version requirements.
 The same program can be installed in several versions without conflicts.
 
+See more in the [technical section](#technical-choices).
 
 ## Objectives, for contributors
 
 **Simple to contribute to.** *you can focus on providing recipes for packages, we handle the tooling*<br />
-We want fewer and simpler tools as possible, even for packaging applications and libraries.
-BaguetteOS ships [a simple tool to package applications](#packaging) and it only requires you to create a very simple recipe for your package.
-It handles [slotting](#slotting), compiling, stripping binaries and libraries, splitting the result into different packages (`-man`, `-lib`, `-doc`, etc.) then authenticate them and finally recreate the index.
-All that, just by typing `packaging app`, nothing more.
+Packaging applications and libraries should be possible with the fewest and simplest tooling possible.
+BaguetteOS provides [a simple tool to package applications](#packaging) (`packaging`) which allows simple recipes for your packages.
+`packaging` handles [slotting](#slotting), compiling, stripping binaries and libraries, splitting the result into different packages (`-man`, `-lib`, `-doc`, etc.), authenticating, etc.
+All that, just by typing
+```sh
+$ packaging app
+```
+nothing more.
 
 <img src="/meanie-makefile.png" alt="meanie meanie dev" class="meanie-img" />
 
 **No Makefile?** *no problem*<br />
 Your application or your library lacks a build system? Here a [tool to create makefiles](#build.zsh).
-It works on any language, yes, even that one.
+It works on any language. *yes, even that one*
 
 **Stable and development versions: same thing.** *slotting, again and again*<br />
 One of the coolest aspect of slotting is: you don't need to change your system *at all* to be on the development version of the OS.
-The development of the newest version of the OS is just slotted in `/usr/baguette-dev` and that's it.
-At any point in time you can execute programs from your stable OS, or if you will, change a few environment variables and be in dev.
+The newest version is just slotted in `/usr/baguette-dev` and that's it.
+Switching OS version is just a few environment variables away.
 
 **New OS, open to explore** *we are open to new ideas*<br />
-BaguetteOS do not suffer from cumbersome historical decisions: no overly engineered package format, no stupidly complex patchwork of mismatch tools.
+BaguetteOS does not suffer from cumbersome historical decisions: no overly engineered package format, no stupidly complex patchwork of mismatch tools.
 
-**Easy to write documentation.** *easy to write, hopefully less procrastination*<br />
-Online documentation is written in Markdown (thanks Zola), and man pages too thanks to `scdoc`.
-Every tool is shipped with a man page: no man page, no integration in base.
+**Easy-to-write documentation.** *and hopefully less procrastination*<br />
+Online documentation and man pages are written in Markdown (thanks to `zola` and `scdoc`).
+Every tool has a man page: no man page = no integration in base.
 
 ## Inspiration
 
-- [CRUX][crux], [alpine][alpine]: simple to understand Linux systems
-- [OpenBSD][openbsd]: security, therefore simplicity, no compromise
-- [PFsense][pfsense]: system and (even advanced) networking administration, yet through a simple website
-- [Plan9][plan9] and [Inferno][inferno]: everything is a file *no seriously guys*
-- [suckless][suckless] and [cat-v][cat-v]: simplicity, code readability and re-usability
-- [morpheus][morpheus]: static compilation for the OS, demystified
+- [CRUX][crux], [alpine][alpine]: simple-to-understand Linux systems
+- [OpenBSD][openbsd]: security-oriented system, therefore simple
+- [PFsense][pfsense]: advanced networking administration through a simple website
+- [Plan9][plan9] and [Inferno][inferno]: OS with an *everything is a file* philosophy *no seriously guys*
+- [suckless][suckless] and [cat-v][cat-v]: documentation and tools, all about simplicity, code readability and re-usability
+- [morpheus][morpheus]: OS based on statically compiled tools
 
 ## Why not use another system?
 
 This section could be expanded.
 
-**A few reasons why any of the candidate covers it all.**<br />
+**A few reasons why none of the candidates cover it all.**<br />
 
 1. **we want slotting**<br />
 So we could change the way we install and maintain packages.
-2. **we want fast install and start-up on dumb devices**<br />
+2. **we want fast install and startup on dumb devices**<br />
 Coreutils shrank to bare minimum, thanks to `toybox`.
-We won't require a full-feature system with several hundred megabytes of used disk-space.
+We won't require a full-feature system with several hundred megabytes of disk-space used.
 3. **documentation is important, but not for all installations**<br />
-Your 42nd test install on a virtual machine doesn't need to provide manual for CLI tools you won't use since you do everything through the web interface.
+Your 42nd test install on a virtual machine doesn't need a manual for CLI tools you won't use since you do everything through the web interface.
 Software and its documentation will be split: manual pages won't be provided by default.
-4. **we want automatic tests, and to allow people to test our system**<br />
+4. **we want automatic tests, and to enable people to test our system**<br />
 We want easy chroot installs, on any system.
 5. **we want to run on tiny ARM boxes, old laptops, top-notch servers**<br />
 So we need to run on any available kernel.
@@ -151,24 +156,23 @@ We don't accept to follow updates from an upstream OS that could break our syste
 
 **Now, let's take a look at each candidate.**
 
-**OpenBSD.** *we will get there quick, but focus on Linux a bit before* <br />
-We definitively want to use OpenBSD, currently we just focused on Linux for hardware compatibility reasons (and out of habits) but it's not set in stone.
+**OpenBSD.** *we will get there quick, but will focus on Linux a bit before* <br />
+We definitively want to use OpenBSD, currently we just focus on Linux for hardware compatibility reasons (and out of habits) but it's not set in stone.
 We love OpenBSD big time, some of us use it daily.
 We aim at providing rootfs for running our system under an OpenBSD kernel and environment.<br />
 *(also, snapshots could be great, guys)*
 
 **PFsense.** *network focused* <br />
-Way too focused on networking.
-Great system, does the job very well, but won't fit our objectives.
+Great system, does the job very well, but won't fit our objectives as it is way too focused on networking.
 
 **CRUX and Alpine.** *great source of inspiration* <br />
 We **do** use the CRUX's `rc` script, and as Alpine it is a source of inspiration for package recipes. 
 However, since we have to change all packages to get slotting, the service manager to have tokenized services, the packaging software to get declarative recipes (...), why even bother use those systems?
 
-**GUIX and coe.** *not simple enough*<br />
-This approach of package management is interesting, having to learn a language to make recipes isn't.
-And that sums a lot about this technology.
-It's great to have, not to put everywhere.
+**GUIX (and Nix).** *not simple enough*<br />
+GUIX approach of package management is interesting, having to learn a language to make recipes isn't.
+And that sums up this technology pretty well.
+It's great, but not to put everywhere.
 Every part of BaguetteOS is simple to understand, GUIX is not simple *enough*.
 But keep it up guys, it's still awesome.
 
@@ -197,8 +201,8 @@ A bootable system to install in virtual machines or bare metal, a rootfs to use
 
 **SysV-style init + [CRUX-like /etc/{rc,mdev.conf,...}][baguette-rc]**. *easy to read, easy to adapt*<br />
 The init could come from toybox or another minimalist project.
-The [rc script from CRUX][cruxinit] is simple to understand and to adapt to any requirement, so we used it.
-We also added some other scripts, like [for profile][baguette-profile] so we can easily manage slotting.
+The [rc script from CRUX][cruxinit] is simple to understand and to adapt to any requirements, so we use it.
+We also provide some other scripts, like for [profile][baguette-profile] so we can easily manage slotting.
 No systemd BS.
 
 **Toybox.** *the megabyte coreutils*<br />
@@ -209,12 +213,12 @@ For the base system, that's all we need.
 **ksh and zsh**. *the first for scripts and root, the other for users*<br />
 [Ksh][ksh] is a very stable and reliable shell from AT&T, trusted by the paranoid people of OpenBSD.
 That's a safe choice for a base system and the root account. 
-On the other hand, we do use [zsh][zsh] daily, as for many users, so we may use it for development or build scripts but not in base.
+On the other hand, we do use [zsh][zsh] daily, as for many users, so we may use it for development or build scripts but not in the base system.
 
 **[Service][service] for service management** *tokenized service description, templating and dumb cli tools for the win* <br />
 [See custom tools.](#custom-tools)
 
-**[Package][package] for package management** *simple, efficient, dead simple code* <br />
+**[Package][package] for package management** *simple-to-use, efficient, dead simple code* <br />
 [See custom tools.](#custom-tools)
 
 **OpenSSH.** *as we all know and love*<br />
@@ -223,7 +227,7 @@ Let's try not to shoot ourselves in the foot.
 
 That's all you need for starters. Web administrative interface will be added to the base when ready.
 
-## Development, build tools, contribution
+## Development, build tools
 
 **Default building tools** *every tool needed to bootstrap*<br />
 Clang (+ LLVM) is the default C (and C++) compiler.
@@ -241,7 +245,7 @@ Our software man-pages are written with `scdoc` so anyone can contribute.
 **Slotting.** *custom file system hierarchy*<br />
 Our FS is not FHS-compliant, partially because of the origin-based slotting.
 There is a strict separation between core system and third party software.<br />
-[More information on slotting.](#slotting)
+[See slotting.](#slotting)
 - `/usr/baguette` for core system programs
 - `/usr/bad` for non slot-able software
 - `/usr/third-party` for other software
@@ -250,7 +254,7 @@ There is a strict separation between core system and third party software.<br />
 
 We are reluctant to add new languages to the base system.
 We will limit the number of languages required for a system bootstrap.
-For now, bootstrapping requires: `C`, `perl`, `m4`, `python` (for stupid reasons).
+For now, bootstrapping requires: `C`, `perl`, `m4`, `python` (for stupid reasons) and `crystal` (used for our software).
 
 However, we think that we can overcome C limitations, explore new possibilities.
 Now, more than ever, we have better alternatives for all non kernel-related tooling.
@@ -262,15 +266,15 @@ We need:
 
 **Crystal language for system tools.** *syntax and productivity of Ruby, the speed of C*<br />
 It is as simple to learn as a dynamic (oriented object) language, while at the same time being almost as fast as C.
-Technically, Crystal is strongly typed which catches errors at compile-time, but with type inference so it is not cumbersome to use.
+Technically, Crystal is strongly typed so it catches errors at compilation-time, but with type inference so it is not cumbersome to use.
 Applications are compiled in a simple binary, easy to deploy.
-There is a good documentation, we used it for long enough to tell.
+There is a good documentation, we have used it for long enough to tell.
 Technical choices are reasonable and documented.
 Finally, Crystal has a large library with all we need for our system components.
 
 There is not much of a drawback here.
-Yes, this is a language you have to learn to work with us on a couple of projects but you can learn it in about a few days to a week and it increases our productivity like crazy.
-We heard about `nim` and a ton of other languages, lot of them are great candidates, but **choices needed to be made**.
+Yes, this is a language you have to learn to work with us on a couple of projects, but you can learn it in about a few days to a week and it increases our productivity like crazy.
+We heard about `nim` and a ton of other languages, lots of them are great candidates, but **choices needed to be made**.
 This is the one reaching the sweet spot between these parameters:
 
 - productivity (the package manager was mostly done in a few days, [and is just a few hundred lines long][package])
@@ -289,6 +293,10 @@ version = application version
 release = recipe version
 $name-$version-r$release.pkg
 ```
+Example:
+```sh
+firefox-79.0-r8.pkg
+```
 
 <a name="custom-tools"></a>
 <a name="top"></a>
@@ -816,14 +824,14 @@ end
 That's easy to write [even in plain C](https://git.baguette.netlib.re/Baguette/libipc/src/branch/master/examples/pongd.c).
 
 
-Its explanation goes beyond the scope of this page… but the tool is awesome and performances are crazy (we have to tell the world!).
+LibIPC explanation goes beyond the scope of this page… <red>and may even deserve a whole website of its own</red> but the tool is awesome and performances are crazy (we have to tell the world!).
 [Just go and check!][libipc]
 
 <red>Explain remote communications.</red>
 Remote remote communications are transparent.
-    - clients and services do not need remote communication
-    - any client can join remote services via any communication protocol
-    - any service is implicitly accessible from anywhere, anyhow
+- clients and services do not need remote communication
+- any client can join remote services via any communication protocol
+- any service is implicitly accessible from anywhere, anyhow
 
 ---