nortti
/
sortix-mirror
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Add manual pages.

This commit is contained in:
Jonas 'Sortie' Termansen 2015-10-06 00:32:45 +02:00
parent e6a1cd6dee
commit b24103d458
15 changed files with 831 additions and 908 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
Makefile
View File

@ -157,6 +157,7 @@ sysroot-base-headers: sysroot-fsh
.PHONY: sysroot-system
sysroot-system: sysroot-fsh sysroot-base-headers
cp -RT share "$(SYSROOT)/share"
export SYSROOT="$(SYSROOT)" && \
(for D in $(MODULES); do ($(MAKE) -C $$D && $(MAKE) -C $$D install DESTDIR="$(SYSROOT)") || exit $$?; done)
@ -361,10 +362,7 @@ sortix.iso.xz: $(SORTIX_BUILDS_DIR)/$(BUILD_NAME).iso.xz
# Release
$(SORTIX_RELEASE_DIR):
mkdir -p $@
$(SORTIX_RELEASE_DIR)/$(VERSION): $(SORTIX_RELEASE_DIR)
$(SORTIX_RELEASE_DIR)/$(VERSION):
mkdir -p $@
$(SORTIX_RELEASE_DIR)/$(VERSION)/builds: $(SORTIX_RELEASE_DIR)/$(VERSION)
@ -385,14 +383,6 @@ release-tar: $(SORTIX_RELEASE_DIR)/$(VERSION)/builds/$(BUILD_NAME).tar.xz
.PHONY: release-builds
release-builds: release-iso.xz release-tar
$(SORTIX_RELEASE_DIR)/$(VERSION)/doc: $(SORTIX_RELEASE_DIR)/$(VERSION) doc doc/*
cp -RT doc $(SORTIX_RELEASE_DIR)/$(VERSION)/doc
rm -f $(SORTIX_RELEASE_DIR)/$(VERSION)/doc/.gitignore
rm -f $(SORTIX_RELEASE_DIR)/$(VERSION)/doc/Makefile
.PHONY: release-doc
release-doc: $(SORTIX_RELEASE_DIR)/$(VERSION)/doc
$(SORTIX_RELEASE_DIR)/$(VERSION)/README: README $(SORTIX_RELEASE_DIR)/$(VERSION)
cp $< $@
@ -409,10 +399,10 @@ $(SORTIX_RELEASE_DIR)/$(VERSION)/repository/$(HOST): sysroot $(SORTIX_REPOSITORY
release-repository: $(SORTIX_RELEASE_DIR)/$(VERSION)/repository/$(HOST)
.PHONY: release-arch
release-arch: release-builds release-doc release-readme release-repository
release-arch: release-builds release-readme release-repository
.PHONY: release-shared
release-shared: release-doc release-readme
release-shared: release-readme
.PHONY: release
release: release-arch release-shared

31
README
View File

@ -41,42 +41,25 @@ such as VirtualBox and Qemu:
Documentation
-------------
You can find the documentation for Sortix use and development at your local
documentation mirror, for instance:
The documentation directory in a Sortix system:
/share/doc
The doc directory inside the Sortix source repository:
doc/
The official Sortix website:
https://sortix.org/doc/
The system is documented as manual pages. Introductory system usage is covered
in the user-guide(7) manual page.
Building Sortix
---------------
If you wish to build Sortix under Sortix itself, please consult the user guide:
Development of Sortix under itself is covered in development(7).
$MY_LOCAL_DOCUMENTATION_MIRROR/user-guide
Development from another operating system is covered in cross-development(7).
If you wish to cross-build Sortix from another operating system, please read
the cross development guide:
You can view the cross-development(7) manual page with this command:
$MY_LOCAL_DOCUMENTATION_MIRROR/cross-development
Documentation
-------------
Basic usage of the system has been documented at:
$MY_LOCAL_DOCUMENTATION_MIRROR/user-guide
man share/man/man7/cross-development.7
License
-------
Copyright(C) Jonas 'Sortie' Termansen <sortie@maxsi.org> and contributors 2011,
2012, 2013, 2014.
2012, 2013, 2014, 2015, 2016.
Sortix is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A

2
doc/Makefile
View File

@ -5,11 +5,9 @@ include ../build-aux/dirs.mak
DOCUMENTS:=\
cross-compilation-sins \
cross-development \
obsolete-stuff \
porting-guide \
posix-divergence \
user-guide \
welcome \
all: $(BINARIES)

282
doc/cross-development
View File

@ -1,282 +0,0 @@
Sortix Cross Development Guide
==============================
The primary way to build Sortix is on Sortix itself. However, the system may not
be fully up to the task yet and your favorite development environment may not
have been ported. You can cross-compile Sortix from a reasonable similar system
such as GNU+Linux. The build process will liberally use common GNU tool options,
so you may wish to install the basic GNU distribution or compatible.
Overview
--------
To build Sortix you need these components:
* Sortix source tree
* Sortix binutils
* Sortix gcc
* GRUB2 (iso support)
* xorriso (iso support)
In this tutorial we will cross-compile a Sortix using by following these steps:
1. Retrieve all the source code.
2. Build additional Sortix-specific tool programs.
3. Create a system root containing all the Sortix system headers.
4. Compile a new compiler that targets Sortix and uses the system root.
5. Actually compile Sortix.
It is necessary to compile binutils and gcc because your system compilers
doesn't produce executables for Sortix, but rather for your current system.
Source Code
-----------
You can find the latest Sortix source code at:
https://gitlab.com/sortix/sortix
You can find the latest Sortix binutils source code at:
https://users-cs.au.dk/sortie/sortix/toolchain/sortix-binutils-latest.tar.xz
You can find the latest Sortix gcc source code at:
https://users-cs.au.dk/sortie/sortix/toolchain/sortix-gcc-latest.tar.xz
It is only possible to build Sortix with this blessed toolchain or a derivative
thereof as it has been customized to understand Sortix and provide a number of
useful extensions. You may need to occasionally upgrade the toolchain, in the
event that it is further modified and Sortix takes advantage of these changes.
Variables
---------
This guide uses shell variables to denote where you have choice. You would
typically decide to set them up somewhat like this:
# The Sortix source code is in /home/user/sortix
# The cross-compiler is installed in /home/user/opt/x86_64-sortix
SORTIX_PLATFORM=x86_64-sortix
CROSS_PREFIX=/home/user/opt/x86_64-sortix
SORTIX_SYSROOT=/home/user/sortix/sysroot
export PATH="/home/user/opt/x86_64-sortix/bin:$PATH"
export PATH="/home/user/opt/x86_64-sortix/sbin:$PATH"
The following sections describe these variables in detail.
Target Platform
---------------
You need to decide what the platform your final Sortix system will run on. You
can currently decide between i486-sortix and x86_64-sortix. In this guide we
will refer to that platform triplet as $SORTIX_PLATFORM. If you want to build
another platform afterwards, then you will have to follow this guide again.
Cross-Environment
-----------------
You should install your cross-toolchain into a useful and isolated directory
such as $HOME/opt/$SORTIX_PLATFORM. This allows you to easily dispose of the
directory and keeps it neatly isolated from the rest of the system. Let's refer
to that location as $CROSS_PREFIX.
You need to add $CROSS_PREFIX/bin and $CROSS_PREFIX/sbin to your $PATH variable:
export PATH="$CROSS_PREFIX/bin:$PATH"
export PATH="$CROSS_PREFIX/sbin:$PATH"
This will modify the $PATH variable in this particular shell session. Depending
on your shell and system configuration you can make this permanent by adding
that line to your ~/.profile. Consult your shell documentation. Otherwise type
it in all Sortix-related shells before doing anything.
Sortix build tools
------------------
You need to install some additional Sortix programs into your local environment
as they are needed to build Sortix. Assuming you cloned the Sortix source code
tree into the ~/sortix directory, you can install them by typing the following
commands:
cd ~/sortix &&
make PREFIX="$CROSS_PREFIX" clean-build-tools &&
make PREFIX="$CROSS_PREFIX" build-tools &&
make PREFIX="$CROSS_PREFIX" install-build-tools &&
make distclean
These tools produce platform independent output so you may wish to install them
into $HOME or /usr/local or where it suits you, and add its bin and sbin to your
$PATH.
Setting up basic system root
----------------------------
The compiler has been taught how to correctly build programs for a Sortix
system, however it gets part of this information from the system headers. The
first step is to create a basic system root that contains the headers and
filesystem structure for the final system. We will install the kernel, libc,
libm, and other core library headers into this directory. Run the following:
cd ~/sortix &&
make sysroot-base-headers HOST=$SORTIX_PLATFORM
This will automatically set up a basic system root in ~/sortix/sysroot. We will
use this when we build the cross-compiler in a moment. Let's call the system
root directory $SORTIX_SYSROOT.
Cross-Toolchain Dependencies
----------------------------
You may need to install these packages (and their development packages) before
building binutils and gcc, or the packages will refuse to configure or some
obscure error will occur. In particular, you may need to install:
* Bison
* Flex
* GNU GMP
* GNU MPFR
* GNU MPC
You should consult the official binutils and gcc documentation on what exactly
you need to install before building these packages yourself.
Cross-Binutils
--------------
We need a cross-binutils that have been taught the Sortix program format. If you
have extracted the Sortix binutils source code into ~/src/sortix-binutils then
you can build binutils out-of-directory using these commands:
mkdir ~/src/binutils-build &&
cd ~/src/binutils-build &&
../sortix-binutils/configure \
--target=$SORTIX_PLATFORM \
--with-sysroot="$SORTIX_SYSROOT" \
--prefix="$CROSS_PREFIX" \
--disable-werror &&
make &&
make install
You may need to install some dependencies before you build binutils. You can
remove the temporary ~/src/binutils-build directory when you are done.
Cross-GCC
---------
We need a cross-compiler that has been taught what Sortix is and that supports a
few extensions that have been added to Sortix gcc that isn't present in upstream
gcc. If you have extracted the Sortix gcc source code into ~/src/sortix-gcc then
you can build gcc out-of-directory using these commands.
mkdir ~/src/gcc-build &&
cd ~/src/gcc-build &&
../sortix-gcc/configure \
--target=$SORTIX_PLATFORM \
--with-sysroot=$SORTIX_SYSROOT \
--prefix="$CROSS_PREFIX" \
--enable-languages=c,c++ &&
make all-gcc all-target-libgcc &&
make install-gcc install-target-libgcc
You may need to install some dependencies before you build gcc, such as libmpc,
libmpfr and libgmp. You can remove the temporary ~/src/gcc-build directory when
you are done. Notice how we don't build all of gcc as this isn't possible yet.
For instance, the C++ library requires the Sortix libc to have been built.
Building Sortix
---------------
You now have the needed components to build a working Sortix system. If you have
completed the above steps correctly, then you can simply do:
cd ~/sortix &&
make HOST=$SORTIX_PLATFORM
This will compile a basic Sortix system into ~/sortix/sysroot with a kernel,
headers, libraries, programs, everything you need. This isn't a bootable system
yet. You need the combination of a kernel and an initrd to boot Sortix. The
initrd is a root filesystem entirely in memory that is loaded by the bootloader
in addition to the kernel. You can generate the initrd in builds/ by running:
cd ~/sortix &&
make HOST=$SORTIX_PLATFORM initrd
If you want a copy of the kernel and initrd in the current directory (rather
than normally finding them in builds/ and sysroot/), you can run:
cd ~/sortix &&
make HOST=$SORTIX_PLATFORM sortix.bin sortix.initrd
You now have a sortix.bin and sortix.initrd pair. You can boot Sortix using a
multiboot bootloader by passing them as a multiboot kernel and multiboot
module/initrd.
If you have xorriso and grub-mkrescue from GRUB 2 installed, then you can
can build a bootable .iso by typing:
cd ~/sortix &&
make HOST=$SORTIX_PLATFORM sortix.iso
This will produce a sortix.iso file that is bootable on real hardware and
virtual machines. This works by first building Sortix system and packaging up an
initrd, then it create a cdrom image with a bootloader configured to load the
kernel and initrd stored on the cdrom. If the command fails, see below.
You can clean the source directory fully:
cd ~/sortix &&
make distclean
This will clean all the source directories and ports and delete all the builds
and the binary package repositories (if you use ports as below) and it will
delete the system root containing your installed system. Alternatively, you may
be interested in the target `mostlyclean `that doesn't delete binary packages
for ports, as they may take considerable time to recompile. See also the targets
`clean`, `clean-core`, `clean-sysroot`, `clean-repository`, `clean-builds`,
and `clean-ports` which lets you control what is cleaned.
Building Ports
--------------
You can extend your Sortix system with third party software that has been ported
to Sortix. You can find the suitable ports if you visit the download directory
for this release and enter the subdirectory `srctix` which contains compressed
archived source tixes. Each such file is simply a compressed tarball that
contains a single directory with the source code for this port. If you have the
file `libfoo.srctix.tar.xz`, you can extract it into ~/sortix/ports as such:
cd ~/sortix &&
mkdir -p ports &&
cd ports &&
tar --extract --file $HOME/Downloads/libfoo.srctix.tar.xz
This will create the directory `~/sortix/ports/libfoo` that contains the source
code for the libfoo port. Keep in mind that many ports depends on another more
basic ports and you will need to satisfy the dependencies. The build process
will give an error and tell you which dependency was missing if you haven't
satisfied the dependencies. Other ports have optional dependencies which gives
an inferior installation if the dependencies are not satisfied.
If you have installed the Tix package management (which is done by the
`make install-build-tools` command above), then the top-level makefile will
automatically detect all the installed ports. They will automatically be built
along with the core system the next time you build Sortix and is present in
your initrd and bootable images.
For more information on ports and how they work, please read:
$MY_LOCAL_DOCUMENTATION_MIRROR/porting-guide
Building some ports may require additional tools to be installed on your system
and other unforeseen problems may arise that means the port doesn't compile
properly on your system. Should a port fail to compile, then the `tix-build`
command will offer you a chance to investigate the situation in a shell.
Troubleshooting
---------------
If producing a bootable cdrom with grub-mkrescue gives the error
xorriso : FAILURE : Cannot find path '/efi.img' in loaded ISO image
then your GRUB grub installation is defective. You need to install mformat(1) to
use grub-mkrescue.

580
doc/user-guide
View File

@ -1,580 +0,0 @@
Sortix User Guide
=================
Thanks for your interest in Sortix! This document will describe how to use it
and what features are available. Sortix is a small self-compiling Unix-like
Operating System developed since 2011. The system is free software licensed
under the GNU General Public License and other licenses.
Introduction
------------
If you are using a Sortix live medium or a prebuilt harddisk image, you will
likely be met with a bootloader. Normally, GNU GRUB is used as the Sortix
bootloader. In that case, simply pick Sortix from the boot menu. If you have
installed Sortix manually, you will have to configure your bootloader to boot
Sortix.
The bootloader will then load the Sortix kernel and start the system. The
initialization process will spawn a shell shortly. The command line is similar
to those of Unix systems and many common Unix commands are available.
Keyboard Layout
---------------
The kernel translates the raw keyboard scancodes into unicode codepoints using
the current keyboard layout table associated with the terminal. Such layout
tables are compiled from a textual description into compressed binary tables
using the `kblayout-compiler` program. The kernel has a default US keyboard
layout integrated into it at compile time.
You can change the current keyboard layout using the `chkblayout` program. It
loads a keyboard layouts with the requested name from the `/share/kblayout`
directory, or a user-supplied file if the path contains a slash. The system
comes with a few existing keyboard layouts and more can be added if desired.
* `dk'
* `us'
You can select a particular keyboard layout by typing something like:
chkblayout da_DK
Mind that while the user-space programs and the kernel all handle text correctly
as unicode, your console may not be able to render such code points. VGA text
mode consoles, for instance, only has the VGA font available, which contains
just codepage 437 characters. The console driver helpfully translates some
unicode characters that look like codepage 437 characters into their lookalikes
for rendering. The graphical kernel console reuses the VGA font internally, but
has no hardware restrictions. In principle, support could be added such that
user-space can upload font data to the kernel graphical console.
Changing the Video Mode
-----------------------
After boot, the screen resolution will be default be in VGA text mode. This only
allows 80 columns and 25 rows of 16 color ASCII text. Naturally, this is very
limited but works on most systems.
You can change the display resolution using the `chvideomode` program. However,
you need a suitable kernel driver to do the mode setting. The current release
only has a simple BGA driver, which works in virtual machines such as Qemu,
VirtualBox or Bochs.
The BGA driver can support virtually any resolution, but since the interface
fails to report which resolutions are appropriate in the current context, I have
simply hard-coded whatever resolutions I found reasonable when I wrote it.
Powering Off
------------
Unless you are using a harddisk image or your initrd has been specially
configured to mount a permanent root filesystem, then this environment is
entirely temporary. You will loose all modifications when powering off the
current system.
The system automatically reboots when the initial shell exits. You can exit the
current shell by entering `exit`, which if entered from the initial shell will
reboot the entire system (losing any changes if the root filesystem is not
permanent). Additionally, you can press Control-D ('^D') to exit the current
shell, but the initial shell will require you to enter a literal `exit` before
it exits and the system reboots.
The init process will restart the shell in the event that it crashes or dies
from a signal. You can use the `kill $$` command to kill the current shell, and
if it is the initial shell, you will get a new shell.
More Documentation
------------------
The system documentation (at least what has been documented so far) is installed
in the `/share/doc` directory. You can view these documents (well, the ones that
are plain text, there is no `man` program yet) using the `editor` program, which
you exit by pressing Control-Q ('^Q'). It is probably a good idea to change
the resolution using the `chvideomode` program if drivers are available.
If your release contains third party software, then this directory may also
contain documentation for this software, which may or may not be easily
viewable using the editor.
Filesystem Structure
--------------------
This as an incomplete list of the common top level directories in Sortix.
* `/bin` - Programs.
* `/boot` - Kernel images, initrd images.
* `/dev` - Device filesystem.
* `/etc` - System-wide configuration.
* `/home` - User directories.
* `/include` - Header files.
* `/libexec` - Non-user programs.
* `/lib` - Shared libraries.
* `/root` - Directory of the root user.
* `/share` - Architecture independent files.
* `/share/doc` - Documentation.
* `/share/kblayout` - Keyboard layouts.
* `/src` - System source code.
* `/tmp` - Temporary files.
Some of these directories not be present or empty on your installation.
Using the Shell
---------------
Sortix features a homemade shell, which at best can be described as hacky.
Despite that, it does have some key features. Here are the features that are
supported:
* Processes can be started in the usual Unix manner.
* Tab-completion.
* Line editing.
* History.
* Background tasks ('&').
* Standard redirection ('<', '>', '>>').
* Piping stdout from a task to stdin of another ('|').
* Stopping the currently running task (Control-C, '^C').
* Waiting for a task to complete and executing the next (';').
* Setting environmental variables ('FOO=bar').
* Using $FOO to insert an environmental variable.
* Listing all environmental variable ('env').
* Changing the current directory ('cd /home').
* Removing an environmental variable ('unset FOO').
* Clearing all enviromental variables ('clearenv').
* Executing shell scripts ('sh script.sh param1 param2').
* Escaping some special characters ('\').
* Comments ('#').
* Exiting the shell ('exit') ('exit 42').
* Basic wildcards ('foo*.bar').
* Clearing the screen (Control-L, '^L').
* Deleting the last typed word (Control-W, '^W').
* Deleting everything before the cursor (Control-U, '^U').
* Deleting everything after the cursor (Control-K, '^K').
* Go to start of line (Control-A, '^A', Home).
* Go to end of line (Control-E, '^E', End).
* Move between words (Control-arrows).
* Quotes (''') ('"').
These features are missing from the shell:
* Proper recursive shell grammar parsing.
* Heredoc sequences.
* Command substitution ('$(ls)', '`ls`').
* Arithmetic expansion ('$((2 + 2))').
* Aliases.
* Conditions and loops ('if', 'case', 'while', 'until', 'for').
* Functions.
* Some special parameters ('$@', '$*', '$#', '$-', '$!).
* Special shell variables ('$ENV', '$IFS', '$LINENO').
* Shell prompt customization ('$PS1', '$PS2', '$PS4').
* Tilde expansion ('~/foo').
* Any but the simplest variant of Parameter Expansion.
* Proper shell wildcard support ('*/*.foo').
* Ability for variables to not be exported.
* Export keyword ('export FOO', 'export BAR=bar').
* Subshells.
* Proper redirection to/from specific file descriptors.
* And much more; the shell remains hacky.
If a better shell is installed, and the shell is non-interactive, then the sh
program will automatically run the superior shell transparently.
Included Programs
-----------------
Sortix comes with a number of home-made programs. Here is an overview:
* `asteroids` - remake of the classic asteroids game
* `basename` - strip directory from filenames
* `benchctxswitch` - useless benchmark
* `benchsyscall` - slightly less useless benchmark
* `carray` - convert a binary file to a C array
* `cat` - display file on terminal
* `chkblayout` - change keyboard layout
* `chmod` - change file mode bits
* `chroot` - change the root directory
* `chvideomode` - change display resolution
* `clear` - clear terminal
* `colormake` - colorful version of make (if make is available)
* `column` - format lines nicely in columns
* `cp` - copy file
* `date` - display current time and date
* `df` - report file system disk space usage.
* `dirname` - strip last component from file name
* `dispd` - non-existent display server
* `du` - report file and directory disk usage
* `echo` - print command line arguments
* `editor` - text editor
* `env` - run a program in a modified environment
* `expr` - evaluate expressions
* `extfs` - ext2 filesystem server
* `false` - exit with an error status
* `find` - recursively list files
* `head` - display start of file
* `help` - show list of available programs
* `id` - print real and effective user and group IDs
* `init` - system management deamon
* `initrdfs` - tool for examining initrds
* `install` - installs a program into a system directory
* `kernelinfo` - display kernel information
* `kill` - send signal to process
* `ln` - create filesystem links
* `ls` - list contents of directory
* `mbrfs` - create partitions for master boot record block device
* `memstat` - print memory information
* `mkdir` - create directory
* `mkinitrd` - create an initrd
* `mktemp` - create temporary file or directory
* `mv` - move a file
* `pager` - display file page by page
* `ps` - report a snapshot of the current processes
* `pstree` - display a tree of processes
* `pwd` - print current directory path
* `realpath` - canonicalize filesystem paths
* `regress` - run system tests
* `rm` - remove file
* `rmdir` - remove empty directory
* `sh` - command shell
* `sleep` - delay for a specified amount of time
* `sort` - sort lines of text files
* `stat` - display file status
* `tail` - display end of file
* `time` - measure program running time
* `trianglix` - triangle system
* `tr` - translate, squeeze and/or delete characters
* `true` - exit with a success status
* `type` - type raw characters directly into the terminal
* `uname` - system information
* `uniq` - report or omit repeated lines
* `unmount` - unmount filesystem
* `uptime` - time since initialization
* `wc` - count words and lines
* `which` - find path to command
* `yes` - repeatedly output a line
Third Party Software
--------------------
In addition, a selection of third-party software has been ported and may be
present on your installation. In particular, the following software packages are
known to work at some level of stability:
* binutils
* bison
* bochs
* bzip2
* dash
* diffutils
* gawk
* gcc
* gettext (GNU)
* git
* grep (GNU)
* groff
* gzip (GNU)
* hello (GNU)
* libassuan
* libatk
* libav
* libcairo
* libdaala
* libdbus
* libexpat
* libffi
* libfontconfig
* libfreetype
* libgcrypt
* libgdk-pixbuf
* libglib
* libGL (Mesa)
* libgmp
* libgnutls
* libgpg-error
* libgtk
* libharfbuzz
* libiconv
* libjpeg
* libksba
* libmpc
* libmpfr
* libnettle
* libogg
* libpango
* libpixman
* libpng
* libSDL
* libssl (LibreSSL)
* libstdc++
* libtheora
* libvorbis
* libwayland
* libxkbcommon
* libz (Sortix)
* m4 (GNU)
* make (GNU)
* patch (GNU)
* python
* quake
* sed (GNU)
* tar (GNU)
* xz
* (and more)
More software will be ported in the future as the system matures. Your release
may not contain all the ported software because of disk space constraints or
the stability/usefulness of the package or the difficulty to build.
Included Games
--------------
The system comes with a number of small casual games. Note that some games
require running in the correct display mode before they will function.
### Asteroids ###
Mine for crystals in an asteroid field! Start the `asteroids` program and if you
have the needed driver support, you can explore space in a gloriously rendered
asteroid field of bitmap graphics. Use the arrow keys to navigate. Avoid the
white asteroids as they will destroy your space ship. Use the `space` key to
fire a laser beam that breaks the asteroid apart, but beware that the fragments
will accelerate. Alternatively, use the `Left Control` key to shoot a fireworks
of laser beams, but it doesn't reach as far and may split a big asteroid into
many small dangerous asteroids. Your goal is to collect as many blue crystals as
possible without dying. You can use the `B` key to spawn a bot that will
cluelessly follow you and shoot whatever asteroids it deems dangerous. You can
use the `A` key to spawn a black hole (or just a big attracting thing).
System Source Code
------------------
The entire system source code (except third party components) is installed into
the `/src` directory. You can use the `editor` program to view and edit the
system source code. If your release contains the GNU compiler collection (gcc),
you can even modify the system and compile custom programs.
Editing Files
-------------
You can use the `editor` program to edit files. The editor itself is fairly
simple to use. It currently supports these keyboard commands:
* `Ctrl-C` - Copy
* `Ctrl-I` - Go to line
* `Ctrl-K` - Cut
* `Ctrl-O` - Open a file
* `Ctrl-Q` - Exit
* `Ctrl-S` - Save a file
* `Ctrl-V` - Paste
* `Ctrl-X` - Cut
* `ESC language <c or c++>` - enable syntax highlighting
* `ESC line-numbering <on or off>` - enable line numbering
* `ESC margin <column>` - add right margin at column
* `ESC popen <command>` - open command output
* `ESC tabsize <desired-tab-size>` - change tab size
It is not currently possible to port third party editors because the terminal
implementation is not standards-compliant enough and is seriously lacking.
Partitions
----------
If the initialization code didn't automatically create block devices for your
partitions, but the harddisk block device itself is supported, you can use the
`mbrfs` program to create block devices for the partitions.
mbrfs /dev/ata0
The program will output the names of the new block devices.
Mounting Filesystems
--------------------
The `extfs` filesystem server translates a block device formatted with the
second extended filesystem and mounts it at an empty directory. The filesystem
may need to be carefully configured as not all ext2 features are currently
supported. In particular, only the `large_file` and `filetype` features are
supported. There is no support for formatting or checking filesystems yet, this
will have to be done from an external system. If the device `/dev/ata0p1`
contains an ext2 filesystem, then it can be mounted using:
mkdir /mnt
extfs /dev/ata0 /mnt
You can then access the filesystem at `/fs`. You can unmount it safely when you
are done using it:
unmount /mnt
This will safely shut down the filesystem process and sync to disk. Beware how
init doesn't know about your personal mount points and powering off the system
will cause all processes to be destroyed, and such mount points will not be
shut down gracefully at the moment.
Graphical User Interface
------------------------
The `dispd` display server is still under development. Sortix does not feature
any documented graphical user interface at the moment.
Sortix comes with the orthogonal graphical multi-user revolutionary triangle
system Trianglix, an attempt at making the most foreign yet somehow usable user
interface. You just need to run `trianglix` to start it.
Network
-------
Network support is still under development and is not documented at this point.
Unix sockets are available.
Building Sortix under Sortix
----------------------------
You can build Sortix under itself and make modifications to it. It is not yet
possible to build all the the third party software used to build itself, but you
can use the system to improve it until it is possible to build third party
software under it.
You need a version of Sortix that ships its own source code in `/src` and
contains a copy of the GNU Compiler Collection (gcc). Additionally, you should
be booting from a harddisk so that the new kernel is used after a reboot.
Otherwise you can only update to a new user-land.
You can use the `colormake` program instead of regular `make` if you want
colored output, which eases spotting compile warnings and errors. This program
simply invokes the real `make` and colors its output.
The `/src` directory contains a makefile that eases rebuilding the entire system
automatically. To rebuild the entire system simply run:
cd /src
make
chroot /src/sysroot init # to test the new user-land
make sysmerge # to update to the new user-land
This will recompile the entire operating system and install it into the staging
area `/src/sysroot`. This is a full usable image of the root filesystem for a
Sortix installation and you can chroot into it if desired.
The sysmerge target merges the image in `/src/sysroot` onto the current root
filesystem without changing local files, as opposed to a make install that
indiscriminately overwrites everything.
You will be running a new version of everything upon completion, except the
kernel and existing processes will continue to run the old programs. If the root
filesystem is permanent and the computer has been configured to boot from it,
then you can reboot the system by exiting the initial shell. You will then be
running an entirely new system.
### Building System Components ###
The projects that are part of the core system can be easily built and installed
with the provided makefiles. They can be built with this simple sequence:
cd /src/${package}
make
make install
If you wish to install the package somewhere than the default location, you can
use the `PREFIX` (and, depending on your needs, `EXEC_PREFIX`, `BINDIR`,
`LIBDIR`, ...) environmental variable to specify where the program will be
installed:
make PREFIX=/local
make PREFIX=/local install
Additionally, should you require that the package should be installed into a
temporary location before it is fully installed, use the `DESTDIR` environmental
variable:
make PREFIX=/local
make PREFIX=/local DESTDIR=/temporary-location
This will effectively install the package into `/temporary-location/local`, but
the package will expect that it is installed into `/local` when it is run. This
is useful for package management purposes to capture a copy of all the installed
files before they are installed for real.
### The C library ###
The C library (libc) implements the common functions, data types and constants
required by the C programming language standard, POSIX, other standards, and
various Sortix-specific extensions. Most programs for Sortix directly or
indirectly rely on this core library for basic functionality and system calls.
The build process builds a regular user-space C library as well as a
freestanding C library designed for inclusion into the Sortix kernel. After
rebuilding the C library, you may wish to rebuild the entire user-land since
those programs have an older libc version statically linked into them.
### The Math Library ###
The Math Library (libm) provides useful mathematical functions for manipulating
floating-point numbers of various sizes. This implements the <math.h> header as
known from standard C. Like the C library, you will likely want to recompile
large parts of user-land if you update this library.
### The Pthread Library ###
The Pthread Library (libpthread) provides a threading implementation through the
standard header <pthread.h> as known from POSIX. Like the C library, you will
likely want to recompile large parts of user-land if you update this library.
### The Display Daemon ###
The dispd library allows processes to communicate with the dispd server that
handles window management and graphical output. Currently, there is no such
server and the library calls the kernel interface itself. This library allows
games such as asteroids to detect the current resolution and request whatever
resolution they need to function.
### Utility Collection ###
The utility collection contains common programs such as `ls`, `cp`, `mkdir` and
more. These programs allow the basic operation from the command line.
### Benchmarks ###
The system comes with some small and outdated benchmark programs. They don't
currently give any meaningful values, so you should not use them for anything.
### Games ###
The games directory contains the source code for the above mentioned games.
These depend on libdispd.
### mbrfs ###
The `mbrfs` program creates block devices for every partition in the master boot
record in a block device.
### extfs ###
The `extfs` program translates a block device formatted with the second extended
filesystem and mounts it at an empty directory.
### mkinitrd ###
This program produces a Sortix compatible initrd, the file that contains the
initial filesystem used to bootstrap the real root filesystem.
### regress ###
This is a collection of operating system test cases run using the `regress`
driver program.
### carray ###
This program converts a binary file to an C array.
### sh ###
This is the Sortix shell. Currently the `sh` program is a wrapper that looks for
a better non-interactive shell if running a script, otherwise it invokes the
hacky `sortix-sh` program.
### Kernel ###
The Sortix kernel is the core of the Sortix operating system. It provides all
the primitives libc needs to implement a Unix-like environment.
Note that you need to reboot the system to use the new kernel and that you need
a permanent root filesystem or your local changes will be lost.

8
doc/welcome
View File

@ -1,7 +1,3 @@
Welcome to Sortix!
You can view the documentation for new users by typing:
You can view the documentation for new users in the editor by typing:
editor /share/doc/user-guide
Press Control-Q (^Q) to quit the editor.
man user-guide

29
share/man/man5/hostname.5 Normal file
View File

@ -0,0 +1,29 @@
.Dd $Mdocdate: October 5 2015 $
.Dt HOSTNAME 5
.Os
.Sh NAME
.Nm hostname
.Nd initial hostname
.Sh SYNOPSIS
.Nm /etc/hostname
.Sh DESCRIPTION
The
.Nm hostname
file is read on boot by
.Xr init 8
and is used as the system hostname. No hostname is set if the file is missing
and the hostname remains the kernel default.
.Sh FORMAT
The file must contain a valid hostname and no whitespace on a single line.
.Sh FILES
.Bl -tag -width "/etc/hostname" -compact
.It Pa /etc/hostname
System hostname.
.El
.Sh EXAMPLES
.Bd -literal
dragon
.Ed
.Sh SEE ALSO
.Xr sethostname 2 ,
.Xr init 8

43
share/man/man5/kblayout.5 Normal file
View File

@ -0,0 +1,43 @@
.Dd $Mdocdate: October 5 2015 $
.Dt KBLAYOUT 5
.Os
.Sh NAME
.Nm kblayout
.Nd initial keyboard layout
.Sh SYNOPSIS
.Nm /etc/kblayout
.Sh DESCRIPTION
The
.Nm kblayout
file is read on boot by
.Xr init 8
and names a file in
.Pa /share/kblayout
that is loaded and set as the keyboard layout. The default kernel US keyboard
layout is retained if the file is missing.
.Pp
The kernel translates the raw keyboard scancodes into unicode codepoints using
the keyboard layout table associated with the terminal. Keyboard layout
tables are compiled from a textual description with
.Xr kblayout-compiler 1
into compressed binary tables.
.Sh FORMAT
The file must contain a filename of
.Pa /share/kblayout
on a single line.
.Sh FILES
.Bl -tag -width "/share/kblayout" -compact
.It Pa /etc/kblayout
Name of initial keyboard layout.
.It Pa /share/kblayout
Keyboard layouts.
.El
.Sh EXAMPLES
.Bd -literal
dk
.Ed
.Sh SEE ALSO
.Xr chkblayout 1 ,
.Xr kblayout-compiler 1 ,
.Xr tcsetblob 2 ,
.Xr init 8

244
share/man/man7/cross-development.7 Normal file
View File

@ -0,0 +1,244 @@
.Dd $Mdocdate: December 29 2015 $
.Dt CROSS-DEVELOPMENT 7
.Os
.Sh NAME
.Nm cross-development
.Nd operating system development from another operating system
.Sh DESCRIPTION
The
.Xr development 7
manual pages describes the primary way of building the operating system, which
is under itself. The secondary way is to cross-compile it from a sufficiently
similar operating system such as Linux with the GNU tools installed. The build
system assumes the presence of some GNU extensions in the standard command line
tools. This document will detail the process of bootstrapping a Sortix system
from another operating system.
.Ss Overview
To build Sortix you need these components:
.Bl -bullet -compact
.It
Sortix source code
.It
Sortix binutils
.It
Sortix gcc
.It
GRUB (for iso creation)
.It
xorriso (for iso creation)
.El
.Pp
The overall process is:
.Bl -bullet -compact
.It
Retrieving all the source code.
.It
Installing the build tools.
.It
Creating a system root with the system headers.
.It
Creating a cross-compiler.
.It
Cross-compiling the operating system.
.El
.Ss Source Code
You can find the latest Sortix source code at
.Lk https://sortix.org/source/
.Pp
You can find the latest Sortix binutils source code at
.Lk https://sortix.org/toolchain/sortix-binutils-latest.tar.xz
.Pp
You can find the latest Sortix gcc source code at
.Lk https://sortix.org/toolchain/sortix-gcc-latest.tar.xz
.Pp
This is a compiler toolchain that has been modified to support Sortix. The
toolchain is sometimes updated and you will need the latest toolchain to keep
building the latest code.
.Ss Variables
This document will use shell variables to denote where you have choice. You
would typically set them up like this:
.Bd -literal
# The Sortix source code is in /home/user/sortix
# The cross-compiler is installed in /home/user/opt/x86_64-sortix
SORTIX_PLATFORM=x86_64-sortix
CROSS_PREFIX=/home/user/opt/x86_64-sortix
SORTIX_SYSROOT=/home/user/sortix/sysroot
export PATH="/home/user/opt/x86_64-sortix/bin:$PATH"
export PATH="/home/user/opt/x86_64-sortix/sbin:$PATH"
.Ed
.Pp
The following sections describe these variables in detail.
.Ss Target Platform
You need to decide what the platform your final Sortix system will run on. You
can currently decide between
.Sy i486-sortix
and
.Sy x86_64-sortix .
In this guide we will refer to that platform triplet as
.Ev SORTIX_PLATFORM .
If you want to build another platform afterwards, then you will have to follow
this guide again.
.Ss Cross-environment
You should install your cross-toolchain into a useful and isolated directory
such as
.Pa $HOME/opt/$SORTIX_PLATFORM .
This allows you to easily dispose of the directory and keeps it isolated from
the rest of the system. We'll refer to that location as
.Ev CROSS_PREFIX.
.Pp
You need to add
.Pa $CROSS_PREFIX/bin
and
.Pa $CROSS_PREFIX/sbin
to your
.Ev PATH
variable:
.Bd -literal
export PATH="$CROSS_PREFIX/sbin:$CROSS_PREFIX/bin:$PATH"
.Ed
.Pp
This will modify the
.Ev PATH
variable in this particular shell session. You can make this permanent by
adding that line to your
.Pa ~/.profile
or the applicable file for your shell and system. Consult your shell
documentation. Otherwise type it in all Sortix-related shells before doing
anything.
.Ss Build Tools
You need to install some additional build tools as they are needed to build the
operating system. The installed build tools must be in sync with the source
code as described in
.Xr development 7 .
Assuming the source code is in
.Pa ~/sortix ,
you can install them by running:
.Bd -literal
cd ~/sortix &&
make PREFIX="$CROSS_PREFIX" clean-build-tools &&
make PREFIX="$CROSS_PREFIX" build-tools &&
make PREFIX="$CROSS_PREFIX" install-build-tools &&
make distclean
.Ed
.Pp
These tools produce platform independent output so you may wish to install them
into
.Pa $HOME/bin
and
.Pa $HOME/sbin
or
.Pa /usr/local/bin
and
.Pa /usr/local/sbin
or where it suits you in your
.Ev PATH .
.Ss System Root with System Headers
Building the compiler requires the standard library headers being available.
This can be satisfies by creating a system root with the system headers:
.Bd -literal
cd ~/sortix &&
make sysroot-base-headers HOST=$SORTIX_PLATFORM
.Ed
.Pp
This will create a system root at
.Pa ~/sortix/sysroot .
Refer to that directory as
.Ev SORTIX_SYSROOT .
.Ss Cross-toolchain Dependencies
You need to install these libraries (and the development packages) before
building binutils and gcc:
.Bl -bullet -compact
.It
bison
.It
flex
.It
libgmp
.It
libmpfr
.It
libmpc
.El
.Pp
Consult the official binutils and gcc documentation for the exact dependencies.
.Ss binutils
Assuming you extracted the binutils to
.Pa ~/src/sortix-binutils ,
you can build binutils out-of-directory by running:
.Bd -literal
mkdir ~/src/binutils-build &&
cd ~/src/binutils-build &&
../sortix-binutils/configure \\
--target=$SORTIX_PLATFORM \\
--with-sysroot="$SORTIX_SYSROOT" \\
--prefix="$CROSS_PREFIX" \\
--disable-werror &&
make &&
make install
.Ed
.Pp
You can remove the temporary
.Pa ~/src/binutils-build
directory when finished.
.Ss gcc
Assuming you extracted the gcc to
.Pa ~/src/sortix-gcc ,
you can build gcc out-of-directory by running:
.Bd -literal
mkdir ~/src/gcc-build &&
cd ~/src/gcc-build &&
../sortix-gcc/configure \\
--target=$SORTIX_PLATFORM \\
--with-sysroot="$SORTIX_SYSROOT" \\
--prefix="$CROSS_PREFIX" \\
--enable-languages=c,c++ &&
make all-gcc all-target-libgcc &&
make install-gcc install-target-libgcc
.Ed
.Pp
You can remove the temporary
.Pa ~/src/gcc-build
directory when finished. Notice how special make targets are used to not build
all of gcc.
.Ss Building Sortix
With the build tools and cross-compiler in the
.Ev PATH
is it now possible to build the operating system as described in
.Xr development 7
by setting
.Ev HOST
to your value of
.Ev SORTIX_PLATFORM .
This tells the build system you are cross-compiling and it will run the
appropriate cross-compiler. For instance, to build an bootable cdrom image
using a
.Sy x86_64-sortix
cross-compiler you can run:
.Bd -literal
cd ~/sortix &&
make HOST=x86_64-sortix sortix.iso
.Ed
.Pp
This creates a bootable
.Pa sortix.iso .
See the
.Xr development 7
manual page for how to use the build system.
.Ss Troubleshooting
If producing a bootable cdrom with
.Xr grub-mkrescue 1
gives the error
.Pp
.Dl xorriso : FAILURE : Cannot find path '/efi.img' in loaded ISO image
.Pp
then your GRUB installation is defective. You need to install
.Xr mformat 1
to use
.Xr grub-mkrescue 1
in your case.
.Sh SEE ALSO
.Xr make 1 ,
.Xr development 7 ,
.Xr installation 7 ,
.Xr porting-guide 7 ,
.Xr sysinstall 8

258
share/man/man7/development.7 Normal file
View File

@ -0,0 +1,258 @@
.Dd $Mdocdate: December 29 2015 $
.Dt DEVELOPMENT 7
.Os
.Sh NAME
.Nm development
.Nd operating system development instructions
.Sh SYNOPSIS
.Pa /src
.Sh DESCRIPTION
Releases come with the system source code in
.Pa /src .
It can be modified, compiled and installed on the current system.
The source code is built with a
.Xr make 1
build system. The source code can be located in any location, if so, simply
substitute
.Pa /src
with the real location. These instructions only apply to building the operating
system from within itself, those building it from another operating system needs
to follow
.Xr cross-development 7
instead.
.Pp
If you are building a new version of the operation system where build tools have
been added or changed, you first need to install the new tools. This is not
needed when building the matching release. To do so, run as root:
.Bd -literal
cd /src
make distclean # fully clean build directory
make install-build-tools # install new tools
make clean-build-tools # clean for real build below
.Ed
.Pp
To build the base operating system and upgrade the current
system, run as root:
.Bd -literal
cd /src
make # build new operating system in /src/sysroot
make sysmerge # upgrade current operating system with /src/sysroot
.Ed
.Pp
The build system creates a minimal root filesystem structure in the
.Pa /src/sysroot
and builds each operating system component in turn, installing them into the
sysroot. If the source code for ports are placed in
.Pa /src/ports
then they are automatically built as well. The result is a minimal system that
can be turned into working system by adding important configuration such as
.Xr passwd 5 .
.Pp
The
.Sy sysmerge
make target ensures a system is built in
.Pa /src/sysroot
and then uses it to replace the current operating system. It ignores
configuration files and other things that could cause conflicts when merging
with an existing system. The new user-space is running on completition, though
existing processes will be running the old programs. Likewise a reboot is needed
to run the new kernel.
.Ss Root Makefile
The
.Pa /src/Makefile
handles the high level build of the operating system. The important targets
are:
.Bl -tag -width "12345678"
.It Sy all
(default) Build each component in turn and install them into the sysroot.
.It Sy build-tools
Make all build tools.
.It Sy clean
Clean the component directories and the port source code.
.Sy ( clean-core, clean-ports )
.It Sy clean-build-tools
Clean the directories of all build tools.
.It Sy distclean
Run every clean target such that the source code is ready for distribution.
.Sy ( clean-builds, clean-core, clean-ports, clean-release, clean-repository, clean-sysroot )
.It Sy install-build-tools
Install all build tools after making them.
.It Sy iso
Create a release iso in the
.Pa /src/builds
directory after making
.Sy all .
.It Sy mostlyclean
Clean everything except binary packages.
.Sy ( clean-builds, clean-core, clean-ports, clean-release, clean-sysroot )
.It Sy release
Make
.Sy iso
and construct release directory tree in
.Pa /src/release
suitable for online publishing.
.It Sy sortix.iso
Make
.Sy iso
and place it in the current directory as
.Pa sortix.iso .
.It Sy sysmerge
Upgrade the current operating system using the sysroot after making the
.Sy all
target.
.It Sy sysroot-base-headers
Create the sysroot and install only the headers of the standard library and
kernel into it. This is useful when bootstrapping the runtime libraries of the
compiler that need to know about libc prior to building libc.
.El
.Pp
The important environment variables influencing the Makefile are:
.Bl -tag -width "12345678"
.It Ev BUILD
The platform of the current operating system. This defaults to the current machine
and operating system.
.It Ev HOST
Specifies platform on which the compiled code will run. This defaults to the
current machine and operating system. This is used when cross-compiling the
operating system. When cross-compiling the operating system, it must be set to
one of
.Sy i486-sortix
and
.Sy x86_64-sortix .
This must be unset when building the build tools as they run on the current
operating system. The compiler tools are prefixed with this variable if it does
not match
.Ev BUILD.
.It Ev OPTLEVEL
Specifies compiler optimization options that gets added to
.Ev CFLAGS
and
.Ev CXXFLAGS .
.El
.Ss Components
The operating systems components, such as libc and the kernel, each have their
own directory by that name. It contains a makefile that can build and install
that component. This allows building and installing only that component onto
the current operating system.
.Pp
For instance, to build and install libc, run as root:
.Bd -literal
cd /src/libc
make
make install
.Ed
.Pp
System libraries are statically linked and you will have to relink programs with
the new library for changes to take effect. Building the whole operating system
from the root makefile ensures components are built in the right order such that
all programs use fresh libraries.
The root makefile invokes component makefiles with
.Ev SYSROOT
set to
.Pa /src/sysroot
to force the compiler to locate files there. Likewise when installing, it sets
.Ev DESTDIR
to
.Pa /src/sysroot
to make it install files there.
.Ss Directories
In addition to the directories for each operating system component, there are
these special directories:
.Bl -tag -width "12345678"
.It Pa /src/ports
If this directory exists, each subdirectory can contain the source code for a
port that gets built along with the rest of the system.
.It Pa /src/release
The
.Sy release
root makefile target creates this directory and populates it with a directory
structure suitable for online publishing of a release.
.It Pa /src/repository
If ports are present, this directory is made when binary packages are built and
they are stored here. This works as a cache so ports don't have to be rebuilt
every time the operating system is. Packages are also copied from here rather
than the sysroot when making releases.
.It Pa /src/sysroot
This directory is made when building the operating system and the freshly made
files are installed here. The build system uses this as the system root which
forces the compiler to look here for headers and libraries. This ensures a
clean bootstrap where files from the current operating system do not leak into
the new system.
.It Pa /src/sysroot-overlay
If this directory exists, it is added to the initrd of the produced iso and can
contain additional system files.
.El
.Ss Build Tools
Some components are used to build the source code and must match the versions
in the source code being built. These are currently:
.Pp
.Bl -bullet -compact
.It
carray
.It
kblayout-compiler
.It
mkinitrd
.It
tix
.El
.Pp
If the currently installed versions of those tools are older than the ones in
the source code, you must update them. The
.Sy clean-build-tools
root makefile target cleans the applicable directories, the
.Sy build-tools
root makefile target builds them from the source code, and the
.Sy install-build-tools
root makefile target installs the new version. You must clean the compiled
files from the source code afterwards because the compiled tools are intended to
run on the current system, and have not been built properly using
.Pa /src/sysroot .
.Ss Ports
You can place the source code for ports in
.Xr srctix 7
format (has a
.Xr tixbuildinfo 7
file) in the
.Pa /src/ports
directory and they will get built automatically when and installed into the
sysroot when building the whole operating system. Installable binary packages
are created in the
.Pa /src/repository/$HOST
directory using
.Xr tix-build 8
directory and can be installed with
.Xr tix-install 8 .
If an existing binary package exists in the repository, it is used instead of
the building the port again.
.Pp
Ports are currently made using
.Xr cross-development 7
as not all ports can be built natively yet.
.Pp
The ports system is described in detail in
.Xr porting-guide 7 .
.Ss Releases
CD-ROM release of the operating system can be built with the
.Sy iso
root makefile target. This will build the whole operating system, if not done
already, and produce a bootable iso for the current architecture in the
.Pa /src/builds
directory. The
.Sy sortix.iso
root makefile target will do the above and place a
.Pa sortix.iso
file in the current directory.
.Pp
The
.Sy release
root makefile target will run the
.Sy iso
target and prepare a
.Pa /src/release
directory with a directory structure and miscellaneous files suitable for a
formal online release.
.Sh SEE ALSO
.Xr make 1 ,
.Xr cross-development 7 ,
.Xr porting-guide 7

51
share/man/man7/hier.7 Normal file
View File

@ -0,0 +1,51 @@
.Dd $Mdocdate: January 8 2016 $
.Dt HIER 7
.Os
.Sh NAME
.Nm hier
.Nd layout of filesystems
.Sh DESCRIPTION
The filesystem hierarchy is as follows:
.Bl -tag -width "12345678"
.It Pa /
Root directory.
.It Pa /bin
Programs.
.It Pa /boot
Boot programs,
.Xr kernel 7 ,
.Xr initrd 7 ,
bootloader.
.It Pa /dev
Devices.
.It Pa /etc
System-wide configuration.
.It Pa /home
User directories.
.It Pa /include
Development headers.
.It Pa /lib
Development libraries.
.It Pa /libexec
Non-user programs.
.It Pa /mnt
User mountpoints.
.It Pa /root
Directory of the root user.
.It Pa /sbin
System programs.
.It Pa /share
Architecture independent files.
.It Pa /src
System source code.
.It Pa /tix
Package management
.It Pa /tmp
Temporary files.
.It Pa /usr
Symlink to the current directory.
.It Pa /var
Various files.
.El
.Sh SEE ALSO
.Xr user-guide 7

28
share/man/man7/initrd.7 Normal file
View File

@ -0,0 +1,28 @@
.Dd $Mdocdate: October 5 2015 $
.Dt INITRD 7
.Os
.Sh NAME
.Nm initrd
.Nd initialization ramdisk
.Sh SYNOPSIS
.Pa /boot/sortix.initrd
.Sh DESCRIPTION
.Pa /boot/sortix.initrd
is a achieve of a minimal userland loaded by the bootloader and passed to the
.Xr kernel 7
that extracts it into the initial kernel memory root filesystem. The kernel
invokes the
.Xr init 8
extracted from the initrd as
.Pa /bin/init .
.Pp
The initrd is in the custom format made by
.Xr mkinitrd 8
and can be viewed with
.Xr initrdfs 8 .
.Sh SEE ALSO
.Xr initrd 7 ,
.Xr kernel 7 ,
.Xr init 8 ,
.Xr initrdfs 8 ,
.Xr mkinitrd 8

40
share/man/man7/kernel.7 Normal file
View File

@ -0,0 +1,40 @@
.Dd $Mdocdate: October 5 2015 $
.Dt KERNEL 7
.Os
.Sh NAME
.Nm kernel
.Nd operating system kernel
.Sh SYNOPSIS
.Pa /boot/sortix.bin
.Op Fl \-init Ns "=" Ns Ar init-command-line
.Sh DESCRIPTION
.Pa /boot/sortix.bin
is the operating system
.Nm kernel .
It initializes and manages the hardware to provide a multitasking computing
environment. The kernel is a
.Xr multiboot 7
compatible executable loaded by the bootloader along with a companion
.Xr initrd 7
that contains a userland.
.Pp
The kernel extracts the initrd into the initial kernel memory root filesystem
and executes
.Xr init 8
as
.Pa /bin/init .
The computer is powered off if this process exits 0, rebooted if it exits 1,
halted if it exits 2, and paniced otherwise.
.Pp
The options are as follows:
.Bl -tag -width "12345678"
.It Fl \-init Ns "=" Ns Ar init-command-line
The
.Ar init-command-line
argument is split into tokens and used as the command line to invoke the
specified
.Xr init 8 .
.El
.Sh SEE ALSO
.Xr initrd 7 ,
.Xr init 8

10
share/man/man7/undocumented.7 Normal file
View File

@ -0,0 +1,10 @@
.Dd $Mdocdate: December 28 2015 $
.Dt UNDOCUMENTED 7
.Os
.Sh NAME
.Nm undocumented
.Nd this manual page doesn't exist
.Sh DESCRIPTION
This manual page does not exist in Sortix at this time.
.Sh SEE ALSO
.Xr man 1

115
share/man/man7/user-guide.7 Normal file
View File

@ -0,0 +1,115 @@
.Dd $Mdocdate: December 28 2015 $
.Dt USER-GUIDE 7
.Os
.Sh NAME
.Nm user-guide
.Nd basic system usage and overview
.Sh DESCRIPTION
Sortix is a small self-hosting Unix-like operating system developed since 2011.
This document covers matters relevant to new users from other Unix-like
operating systems.
.Ss Introduction
You will be presented a with standard Unix command line environment upon booting
the live environment.
.Ss Shutdown
.Xr init 8
spawns a session after boot. This is a root shell if booted in
single-user mode.
.Pp
To power off from a single-user boot root shell, run
.Sy exit 0
in the shell. To reboot, run
.Sy exit 1
in the shell.
.Ss Keyboard Layout
The kernel has a default US keyboard layout compiled into it.
.Pp
You can change the current keyboard layout using
.Xr chkblayout 1 .
It loads the requested keyboard layout with the requested name from
.Pa /share/kblayout .
For instance to load a Danish keyboard layout:
.Pp
.Dl $ chkblayout dk
.Pp
The system has basic unicode capabilities but the kernel console font is limited
to characters in codepage 437.
.Ss Graphics
The bootloader prepares an appropriate video mode to the best of its abilities.
If you have a supported graphics card:
.Pp
.Bl -bullet -compact
.It
.Xr bga 4 -
Bochs Graphics Adapter found in virtual machines.
.El
.Pp
Then you can run
.Xr chvideomode 1
to change the video mode after boot.
.Pp
.Dl $ chvideomode
.Ss Manual
The system manual can be viewed with the
.Xr man 1
program. Sortix is currently in the process of being documented and many manual
pages are missing. The current priority is to document areas specific to Sortix
and assume standard knowledge from other operating system.
.Ss Editor
.Xr editor 1
is the standard text file editor.
.Ss Games
The base system comes with games such as
.Xr asteroids 6 .
Additional third party games may be installed through ports.
.Ss Filesystem Hierarchy
The filesystem hierarchy is described in
.Xr hier 7 .
.Ss Memory Usage
The
.Xr memstat 1
command shows the current memory usage.
.Ss Third Party Software
Releases come with useful third party software installed. The
.Pa /tix/installed.list
file lists all currently installed ports.
.Ss Source Code
Releases come full with the system source code in
.Pa /src
along with the tools to build it and develop it. The build
process is covered in
.Xr development 7 .
.Ss Mounting
You can mount ext2 partitions using
.Xr extfs 8
and unmount them with
.Xr unmount 8 :
.Pp
.Dl $ extfs /dev/ahci0p1 /mnt
.Dl $ unmount /mnt
.Pp
Beware that
.Xr init 8
is unaware of manual point points and powering off will not gracefully unmount.
The
.Xr extfs 8
driver only supports the
.Sy large_file
and
.Sy filetype
ext2 extensions. You can make a compatible filesystem with:
.Pp
.Dl $ mkfs.ext2 -O none,large_file,filetype
.Ss Networking
Sortix does not have networking at this time. Unix sockets have a basic
implementation incapable of advanced features. The standard library and
kernel provides stubs for many network interfaces.
.Ss Development
The system is self-hosting and is capable of building itself as described in
.Xr development 7 .
Ports are cross-compiled as described in
.Xr cross-development 7 ,
but it is becoming feasible to build a large number of them natively.
.Sh SEE ALSO
.Xr cross-development 7 ,
.Xr development 7