kotovalexarian-likes-gitlab/sortix--sortix
1
0
Fork 0
mirror of https://gitlab.com/sortix/sortix.git synced 2023-02-13 20:55:38 -05:00
Code Releases Activity

Add documentation.

Browse source
This commit is contained in:
Jonas 'Sortie' Termansen 2012-12-21 21:22:09 +01:00
parent 184fce3cf3
commit 425069cbf1
8 changed files with 1056 additions and 165 deletions
Download patch file Download diff file Expand all files Collapse all files

15
Makefile
View file

@ -3,7 +3,7 @@ MAKEFILE_NOT_MEANT_FOR_SORTIX=1
include compiler.mak
include version.mak
MODULES=libc libm dispd games mkinitrd mxmpp utils bench ext mbr sortix
MODULES=doc libc libm dispd games mkinitrd mxmpp utils bench ext mbr sortix
ifndef SYSROOT
SYSROOT:=$(shell pwd)/sysroot
@ -86,6 +86,7 @@ sysroot-overlay: sysroot-fsh sysroot-system
.PHONY: sysroot-user-skel
sysroot-user-skel: sysroot-fsh sysroot-system sysroot-overlay
cp "$(SYSROOT)/share/doc/welcome" -t "$(SYSROOT)/etc/skel"
.PHONY: sysroot-home-directory
sysroot-home-directory: sysroot-fsh sysroot-system sysroot-overlay sysroot-user-skel
@ -301,6 +302,14 @@ release-tar: $(SORTIX_RELEASE_DIR)/$(VERSION)/builds/$(BUILD_NAME).tar.xz
.PHONY: release-builds
release-builds: release-iso.xz release-deb release-tar
$(SORTIX_RELEASE_DIR)/$(VERSION)/doc: $(SORTIX_RELEASE_DIR)/$(VERSION) doc doc/*
cp -R doc -T $(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 $< $@
@ -308,10 +317,10 @@ $(SORTIX_RELEASE_DIR)/$(VERSION)/README: README $(SORTIX_RELEASE_DIR)/$(VERSION)
release-readme: $(SORTIX_RELEASE_DIR)/$(VERSION)/README
.PHONY: release-arch
release-arch: release-builds release-readme
release-arch: release-builds release-doc release-readme
.PHONY: release-shared
release-shared: release-readme
release-shared: release-doc release-readme
.PHONY: release
release: release-arch release-shared

220
README
View file

@ -1,200 +1,94 @@
The Sortix Operating System
===========================
Sortix is a hobby operating system. It was originally created as a tool to learn
more about kernel and operating system design and implementation. Today it is
gradually transforming into a real operating system. The standard library and
kernel is rich enough that some third party software can and has been ported to
Sortix. While the system remains limited, there have been added support for
bitmap graphics and proper filesystem support is being worked on. Unfortunately
there is no support for networking yet. The current release ships with various
test programs, utility programs and a few games and has support for rendering
the console in graphics mode.
The system aims to be an Unix-clone and is heavily based on POSIX. However, I've
drawn much inspiration from systems such as Plan 9, GNU/Hurd and MINIX. While
the system doesn't strive to be a microkernel (and today isn't), the plan is to
have user-space filesystems, per-process namespaces, subusers, and generally
give regular users more power that traditional Unix systems. If you are
interested, you can read about my design decisions at http://maxsi.org/blog/.
Sortix is a small Unix-like operating system developed since 2011 with emphasis
on cleaning up traditional Unix design mistakes while retaining compatibility
with third party software. Much third party software has been ported to Sortix
and the system is now self-building. The Sortix kernel, standard libraries, and
most utilities were written entirely from scratch.
Links
-----
For more information, documentation and news, please visit the official website:
http://sortix.org/
You can also download the newest release and cutting edge nightly builds at:
https://cs.au.dk/~sortie/sortix/release/
You can retrieve the current git master from our gitorious project page at:
https://gitorious.org/sortix/
System Requirements
-------------------
Sortix has very low system requirements. It also works well under virtual
machines such as VirtualBox and Qemu.
Sortix has low system requirements. It also works well under virtual machines
such as VirtualBox and Qemu - however Bochs is not officially supported:
* A 32-bit x86 (with SSE) or 64-bit x86_64 CPU.
* A dozen megabytes of RAM.
* A few dozen megabytes of RAM - or if you are using a cdrom release with ports
then you likely need at least twice the size of the cdrom image.
* A harddisk or cdrom drive or support for booting from USB.
* A multiboot compliant bootloader if booting from harddisk.
* A Parallel ATA harddisk, if you wish to access it from Sortix. SATA is not
supported yet.
Features
--------
The current development version of Sortix offers a traditional multi-process
protected environment with round-robin scheduling. A quick and dirty shell is
able to execute programs in foreground or background mode, handle IO redirection
and piping the standard output of a process into the standard input of another.
A real shell will be added as the system matures and I get around to finish the
work-in-progress shell.
Documentation
-------------
The official distribution contains a number of small utilities one would expect
on a unix system, such as cp, cat, ls, and so on. There are a lot of common
utilities missing as I haven't coded them yet. The purpose of the current
userspace is simply to test the system so don't expect too much.
You can find the documentation for Sortix use and development at your local
documentation mirror, for instance:
Unfortunately, for technical reasons, I don't distribute ported third party
software along with Sortix. This is largely because the build system sucks but
also that statically linked libraries are big and the initrd is already big
enough as it is. However, I have successfully ported binutils, gcc, gzip, zlib,
freetype, GNU hello, and more. Once proper filesystem support is merged, I can
distribute third party software separately and it can be mounted during boot.
The documentation directory in a Sortix system:
/share/doc
A number of small games is present and uses the VGA textmode to render ASCII
graphics. Notably you can play two-player Pong, or single-player Snake, or the
nice and Turing-complete Conway's Game of Life. There is also a small remake of
the asteroids game which uses 32-bit bitmap graphics. These are probably the
main attraction of the system for non-technical people.
The doc directory inside the Sortix source repository:
doc/
The Sortix kernel has very basic filesystem support. The root filesystem / is
simply a single-directory RAM filesystem. The init ramdisk is mounted read-only
on /bin and various devices are accessible through the /dev filesystem. Work is
underway to create an ext2 filesystem server, but it won't be of much use until
the kernel virtual filesystem is completed in the 0.8dev development cycle.
The official Sortix website:
http://sortix.org/doc/
There currently is no concept of users in the system (only the root user
exists). I decided to delay making a multi-user system until the base system is
in place. Note that there is only a single terminal - even though the system is
a multi-process system, there is only a single graphics framebuffer and there is
no framework for sharing it.
Building Sortix
---------------
Improvements in Sortix 0.7
--------------------------
The 0.7 release improves greatly upon Sortix 0.6.
If you wish to build Sortix under Sortix itself, please consult the user guide:
* Multithreaded and fully preemptive kernel.
* Support for Streaming SIMD Extensions (SSE) and floating point numbers.
* Support for bitmap graphics through new /dev/video/ framework.
* Environmental variables.
* Rewritten and powerful initrd format.
* Init restarts the shell if it crashes.
* BGA graphics driver.
* Console rendering in graphics mode.
* Asteroids remake.
* Improved signal handling.
* VEOF support in terminal driver and shell.
* Various shell improvements.
* Implement scanf function family.
* Support for using PAT and MTRR to speed up video memory access.
* Countless improvements to the kernel and the standard library.
$MY_LOCAL_DOCUMENTATION_MIRROR/user-guide
In addition, a BIOS call driver was created during the 0.7 cycle as well as a
VBE graphics driver. However, the BIOS driver only worked on 32-bit CPUs and
hence wasn't merged in time. As the VBE driver depended on it, it was cut too.
If you wish to cross-build Sortix from another operating system, please read
the cross development guide:
Known bugs
----------
There is currently a lot of bugs and small quirks in Sortix. They are caused by
the system being young and incomplete. They will gradually be fixed as the base
system improves. They are tolerated in the releases because they are not
critical and improvement situation from the last release.
$MY_LOCAL_DOCUMENTATION_MIRROR/cross-development
The shell only looks at whitespace when parsing input lines. This means that
operators such as & ; and | must be surrounded by whitespace on both sides.
While quotes aren't implemented, you can work around this by using backslahes
to escape all characters except newlines. The shell does not accept very long
lines yet.
Documentation
-------------
Some programs change the format of the terminal standard input delivered to
them. For instance, the pong game needs to capture every keyboard event. However
running such programs at the same time as programs that need proper line-
buffered input (such as the shell) causes conflicts and neither program gets
what it needs causing programs to exit or crash. Note that if the shell fails
to read in its expected format, it exits with an error code. This issue is
caused by the design of the terminal system and can't be fixed until it is
rewritten.
Basic usage of the system has been documented at:
The editor can only run in 80x25 terminal resolutions. This is because it is
very hacky and was written before malloc worked. This will be fixed when the
editor is rewritten.
The filesystem is currently hacked together in the kernel. When things go wrong
you may experience the utilities returning the wrong error codes. This is
harmless but confusing. All the current kernel filesystem code will be replaced
a user-space filesystem framework and will be present in the next release.
The system can partially deadlock if a process exits and zombie children are not
collected yet.
Improvements scheduled for Sortix 0.8
-------------------------------------
* New build system based on cross compilation and package management.
* Merge BIOS and VBE drivers.
* Kernel virtual filesystem.
* User-space filesystem framework.
* User-space ext2 filesystem driver.
* Refactor and extend the standard library.
* Mount-points.
* Improved terminal framework.
* New and improved shell.
* Copy-on-write in fork(2) and mmap(2).
* Pointer-safe system calls.
* And various misc. improvements.
Technical details
----------------
The system is mostly coded in C++, but also contains a few files in C. However,
the user-land experiences a normal C programming interface as per POSIX.
Executable files natively uses the ELF format used on GNU/Linux and other
systems. There is no shared library support yet, but it'll be possible when I
get around to implement copy-on-write memory, mmap(2) and swapping to disk.
Building
--------
To build the Sortix source code you need to install a few dependencies. First of
all you need the GNU Compiler Collection (C and C++), GNU Make, and GNU
Binutils. You then need to build and install the included macro preprocessor
(mxmpp) somewhere in your PATH such as /usr/bin. You need a GNU/Linux build
system to build Sortix, although, it wouldn't be difficult to port the build
system to other platforms. You can then build the Sortix kernel and user-space
utilities by running make in the Sortix root source directory. By default it
will build to your CPU architecture (64-bit on 64-bit systems, 32-bit otherwise).
Use CPU=x86 or CPU=x64 as arguments to make to control which target is built.
To build a bootable ISO you need GNU GRUB 2, as that is used by "make iso" to
generate the iso. In turn, GNU GRUB relies on xorriso to create the iso file.
You can burn the ISO to a cdrom or dvd, or even dd(1) it onto a USB memory stick
and boot from if it your BIOS supports it. You can also provide it to a virtual
machine. Alternatively you can install the kernel binary and initrd in your
/boot directory and configure GRUB to boot Sortix.
Links
-----
You can visit the official website at http://www.maxsi.org/software/sortix/ for
more information and news. You can also download the newest release and cutting
edge nightly builds from https://cs.au.dk/~sortie/sortix/release/.
You can retrieve the current git master from our gitorious project page from
https://gitorious.org/sortix/.
You can read my blog where I discuss various design decisions in Sortix at
http://maxsi.org/blog/.
$MY_LOCAL_DOCUMENTATION_MIRROR/user-guide
License
-------
Copyright(C) Jonas 'Sortie' Termansen <sortie@maxsi.org> and contributors 2011,
2012.
2012, 2013.
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
PARTICULAR PURPOSE. See the gpl.html and lgpl.html files for more information.
PARTICULAR PURPOSE. See the COPYING-GPL and COPYING-LGPL files for more
information.
See the individual files for copyright terms. If a file does not contain a
license header, you can assume it is released under the GNU General Public
Licenser, either version 3 or (at your option) any later version. This includes
Sortix-related experimental branches and repositories found on Gitorious: these
things are so experimental that I didn't add copyright statements.
things are so experimental that I might not have added copyright statements.
The build scripts might not contain a copyright license in which case they are
covered by the standard license for the software component they relate to.
Unless the license header in the source code states otherwise, the Sortix
kernel, the filesystem servers, the initrd tools, the utilities, the games, and
@ -202,5 +96,7 @@ the benchmark programs are licensed under the GNU General Public License, either
version 3 or (at your option) any later version.
Unless the license header in the source code states otherwise, the libc library
s licensed under the GNU Lesser General Public License, either version 3 or (at
your option) any later version.
and the libdispd library are licensed under the GNU Lesser General Public
License, either version 3 or (at your option) any later version.
The Sortix math library (libm) is licensed as described in the libm/LEGAL file.

1
doc/.gitignore vendored Normal file
View file

@ -0,0 +1 @@
index.html

19
doc/Makefile Normal file
View file

@ -0,0 +1,19 @@
include ../compiler.mak
include ../version.mak
include ../dirs.mak
DOCUMENTS:=\
cross-development \
obsolete-stuff \
user-guide \
welcome \
all: $(BINARIES)
.PHONY: all install clean
install: all
mkdir -p $(DESTDIR)$(DOCDIR)
cp -t $(DESTDIR)$(DOCDIR) $(DOCUMENTS)
clean:

198
doc/cross-development Normal file
View file

@ -0,0 +1,198 @@
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://gitorious.org/sortix/sortix/
You can find the latest Sortix binutils source code at:
https://cs.au.dk/~sortie/sortix/toolchain/sortix-binutils-latest.tar.xz
You can find the latest Sortix gcc source code at:
https://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.
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 to your $PATH variable:
export PATH="$CROSS_PREFIX/bin:$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" build-tools &&
make PREFIX="$CROSS_PREFIX" install-build-tools
These tools produce platform independent output so you may wish to install them
into $HOME/bin or /usr/local/bin or where it suits you in 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 $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="$SYSROOT" \
--prefix="$CROSS_PREFIX" \
--program-prefix=$SORTIX_PLATFORM- &&
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=$SYSROOT \
--prefix="$CROSS_PREFIX" \
--enable-languages=c,c++ \
--program-prefix=$SORTIX_PLATFORM- &&
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. 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/sortix.iso file that is bootable on real hardware
and virtual machines. Alternatively, you can take the sortix.bin file and boot
that with GRUB as a multiboot kernel and sortix.initrd (snapshot of the sysroot)
as a multiboot module/initrd.
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.

215
doc/obsolete-stuff Normal file
View file

@ -0,0 +1,215 @@
Obsolete Stuff
==============
One of the primary design goals of Sortix is to be a modern Unix system with the
old cruft removed. This means that some features/functions/headers in the C API
has been removed, never implemented in the first place, or is scheduled for
future removal. This is likely inconvenient, as a lot of programs still rely on
these obsolete/broken features, which will have to be fixed. Additionally, it'll
further complicate porting programs to Sortix. However, it is our belief that
ultimately such removals will be beneficial and this is merely a transitional
period. In almost all cases, we have made available superior interfaces that can
be used instead.
It may cause problems for portable programs that these features cannot or should
not be used, as lesser operating systems may not implement the modern
replacements. Either fix such systems or add some feature detection magic.
This is a list of common features that may currently be implemented, but that
you shouldn't use and if you do, then you should fix your program before it
breaks when the feature is finally removed.
You might be tempted to use a preprocessor conditional for __sortix__ to detect
the absence of these obsolete features and the availability of their modern
replacements. Keep in mind that other systems may have the modern replacements
and also may have removed features, and that they may supply other extensions to
replace the features. If you need to be portable, you should use whatever means
to automatically detect the availability of features at compile time, rather
than hardcode cases for each platform, as your software is likely to be ported
to platforms that didn't exist when you wrote your code.
asctime, asctime_r
------------------
This function is fundamentally broken. It doesn't support locales, it adds some
useless newline character at the end, the date format doesn't comply with ISO
standards, asctime is not thread safe, and so on. Actually, the POSIX standard
supplies code that implements the function because the format simply cannot
change. The function was actually already deprecated back in 1989 when the
original C standard was released. The solution is today the same as back then,
simply use the much superior strftime function instead. asctime_r tries to make
the function thread safe, but it doesn't fix the other broken semantics. The
only use of this function is to participate in protocols that somehow manages to
use asctime formatted dates, but then you might as well just paste in the POSIX
example code and hard code it in your program.
Sortix currently implement these functions for compatibility reasons.
creat
-----
Use open() instead of this poorly named function. Additionally, open() has a
similarly poorly named flag O_CREAT that does what you need.
Sortix currently implement this function for compatibility reasons.
ctime, ctime_r
--------------
These functions are defined in terms of asctime and asctime_r. Therefore they
will need to be removed as well.
Sortix currently implement these functions for compatibility reasons.
ftime
-----
Use clock_gettime instead.
gethostbyname, gethostbyname
----------------------------
Use the protocol agnostic functions such as getaddrinfo(). For instance, if you
want a HTTP connection to www.example.com, do you really care how the data get
to and from there? Most of the time you want a reliable transport protocol to a
named host, but don't care much about the low-level details. If you use these
modern networking interfaces, then your program can use without modification
IPv4, IPv6, or whatever new protocol is used in the future.
getpgrp
-------
POSIX and BSD disagree on the function prototype for getpgrp. Use getpgid
instead, as everyone agrees on that.
gets
----
Use fgets or getline instead. This function has been removed in the latest C
standard, but most implementations carry it anyways. Curiously it is hated so
much that some compatibility libraries such as gnulib actively use magic to add
deprecation warnings not to use it, but these won't compile because gets isn't
declared in any Sortix headers.
gettimeofday
------------
Use clock_gettime instead.
getwd
-----
Use get_current_dir_name() or getcwd() instead. Don't rely on the existence of
PATH_MAX, but allocate buffers as needed.
isascii
-------
This function is rather pointless. If we use a character encoding that wasn't
ascii compatible, then it doesn't make sense. If we use a sane character
encoding such as UTF-8, then you can simply check if the value is at most 127.
PATH_MAX
--------
There is no such limit in Sortix. The kernel might restrict the path lengths at
some point, but that'll just be to protect against misbehaving processes. You
can use pathconf() or fpathconf() to see if a particular path has a limit, but
otherwise you should just allocate strings as much as needed. There should be
functions in place so you can use paths of any length. If you really need a
limit as a hack to fix a broken program, you can do something like:
#if !defined(PATH_MAX) && defined(__sortix__)
#define PATH_MAX 32768
#endif
If there is ever going to be a path limit, it'll probably be either this value
or higher. Ideally, your programs ought to work with paths of any reasonable
length.
sdl-config
----------
This SDL utility program is basically broken for cross-compilation and seems to
be a poor counterpart to to pkg-config. If you insist on using such config
tools, use pkg-config instead as it causes fewer problems. If you really need a
sdl-config script, implement it using pkg-config:
pkg-config "$@" sdl
The Sortix build system actually injects such a sdl-config into the PATH to make
sure programs don't use the wrong SDL libraries when cross-compiling.
setpgrp
-------
POSIX and BSD disagree on the function prototype for setpgrp. Use setpgid
instead, as everyone agrees on that.
settimeofday
------------
Use clock_settime instead.
strings.h
---------
There must have been some confusion back in the day since this header was
created, rather than the functions just added to string.h. In sane
implementations, you can just include string.h that also declares these
functions. The strings.h header exists in Sortix for source-code compatibility,
but don't be surprised if it just includes the regular string.h.
struct timeval
--------------
This microsecond precision data structure has been fully replaced by struct
timespec, which offers nanosecond precision. All kernel APIs use struct timespec
exclusively.
Sortix currently provides this structure for compatibility reasons.
sys/param.h
-----------
This is a BSD header that contains a bunch of BSD-specific stuff and other
miscellaneous junk. The GNU libc implementation contains some uselese macros
that doesn't justify its existence. The header inclusion can often be deleted
without any problems, but older systems may require its inclusion.
sys/time.h
----------
You don't need this header and it'll be removed at some point. It is filled with
obsolete functions and macros. The only reason you might want it is to get the
declaration of struct timeval, but that data type has been replaced by struct
timespec.
Sortix currently provides this header for compatibility reasons.
sys/timeb.h
-----------
This is a header that contains the ftime function that has been replaced, this
header has been removed as well.
tmpnam
------
There is an inherently race condition prone and has thread safely issues with a
NULL argument. Use tmpfile() instead if you can do with a file whose name you do
not know. Unfortunately, Sortix has yet no satisfying temporary file creation
function that gives you a file and its name without having to deal with silly
template strings and other problems.
utime
-----
Use utimens instead, or perhaps the more portable utimensat.
Sortix currently provides this function for compatibility reasons.
utimes
------
Use utimens instead, or perhaps the more portable utimensat.

546
doc/user-guide Normal file
View file

@ -0,0 +1,546 @@
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
---------------
Only the US Keyboard layout remains supported at this time. Adding new layouts
to the kernel is simple, but the system only supports ASCII text, making support
for international keyboard layouts pointless at this time. Eventually, a program
in user-space will be able to decode the keyboard scancodes, making it no longer
a kernel problem.
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. A VBE driver also exists, however, it is not yet merged
into the mainline version because it causes problems on x86_64 due to missing
BIOS call support. Note that some programs does not work outside of VGA Text
Mode because the dispd library doesn't yet have a VGA->framebuffer converter.
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 (loosing 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.
* /boot - Kernel images, initrd images.
* /dev - Device filesystem.
* /etc - System-wide configuration.
* /home - User directories.
* /include - Header files.
* /root - Directory of the root user.
* /share - Architecture independent files.
* /share/doc - Documentation.
* /src - System source code.
* /tmp - Temporary files.
* /$cputype - Files for $cputype.
* /$cputype/bin - Programs for $cputype.
* /$cputype/lib - Shared libaries for $cputype.
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.
* Background tasks ('&').
* Standard output redirection ('>').
* Piping stdin 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').
* Setting the hostname ('HOSTNAME=sortix-pc').
* Changing the current directory ('cd /home').
* Removing an environmental variable ('unset FOO').
* Clearing all enviromental variables ('clearenv').
* Executing shell scripts ('sh script 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').
These features are missing from the shell:
* Input redirection ('<') ('<<').
* Quotes (''') ('"').
* Proper shell wildcard support ('*/*.foo').
* Escaping newline characters.
* And much more; the shell remains hacky.
Included Programs
-----------------
Sortix comes with a number of home-made programs. Here is an overview:
* `asteroids` - remake of the classic asteroids game
* `benchctxswitch` - useless benchmark
* `benchsyscall` - slightly less useless benchmark
* `calc` - reverse polish calculator
* `cat` - display file on terminal
* `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
* `conway` - game of life simulator
* `cp` - copy file
* `date` - display current time and date
* `dispd` - non-existent display server
* `du` - report file and directory disk usage
* `echo` - print command line arguments
* `editor` - text editor
* `extfs` - ext2 filesystem server
* `find` - recursively list files
* `head` - display start of file
* `help` - show list of available programs
* `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
* `mv` - move a file
* `mxmpp` - silly preprocessor
* `mxsh` - the shell
* `pager` - display file page by page
* `pong` - remake of the classic pong game
* `pwd` - print current directory path
* `rm` - remove file
* `rmdir` - remove empty directory
* `sh` - alias for the shell
* `snake` - remake of the classic snake game
* `tail` - display end of file
* `time` - measure program running time
* `type` - type raw characters directly into the terminal
* `uname` - system information
* `uptime` - time since initialization
* `wc` - count words and lines
* `which` - find path to command
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
* cairo
* dbus
* diffutils
* fontconfig
* freetype
* gcc
* gettext
* git
* grep
* groff
* groff
* gzip
* hello (GNU)
* libassuan
* libatk
* libav
* libcairo
* libdaala
* libexpat
* libffi
* libgcrypt
* libgdk-pixbuf
* libglib
* libGL (Mesa)
* libGLU (Mesa)
* libgmp
* libgnutls
* libgpg-error
* libgtk
* libharfbuzz
* libiconv
* libjpeg
* libksba
* libmpc
* libmpfr
* libogg
* libpango
* libpng
* libtheora
* libvorbis
* libwayland
* libxkbcommon
* m4
* make
* nettle
* openssl
* patch (GNU)
* pixman
* python
* quake
* sdl
* sed (GNU)
* tar (GNU)
* xz
* zlib
* (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.
### Pong ###
The program `pong` implements a simple pong clone that uses the VGA text mode
buffer. Player one controls using `W` and `S`, while player two controls using
the arrow keys. This program is only available in VGA mode.
### Snake ###
This is a simple snake clone that only works in VGA text mode. You control the
snake using the `W`, `S`, `A`, and `D` keys. To run, start the program `snake`.
This program is only available in VGA mode.
### Conway's Game of Life ###
You can do turing-complete calculations in the classic Game of Life in the VGA
text mode buffer. Simply start the program `conway` and use `W`, `A`, `S`, and
`D` to navigate the screen. `Space` toggles the current point between live and
dead. `C` clears the entire screen, and `R` starts and stops the simulation.
This program is only available in VGA mode.
### 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-Q` - Exit
* `Ctrl-O` - Open a file
* `Ctrl-S` - Save a file
* `Ctrl-I` - Go to line
* `ESC tabsize <desired-tab-size>` - change tab size
* `ESC margin <column>` - add right margin at column
* `ESC popen <command>` - open command output
* `ESC language <c or c++>` - enable syntax highlighting
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. You must take care to send the
filesystem server a SIGTERM signal to shut down when you are unfinished,
otherwise the data may not have been synced to disk. This will be done
automatically if the root filesystem was mounted by the initrd. If the device
/dev/ata0p1 contasins an ext2 filesystem, then it can be mounted using:
mkdir /fs
extfs /dev/ata0 /fs
You can then access the filesystem at /fs. There is no real unmount support and
if the file system server shuts down, the system may hang trying to communicate
with a server that isn't there.
Graphical User Interface
------------------------
The `dispd` display server is still under development. Sortix does not feature
any documented graphical user interface at the moment.
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 made 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
will have to be satisfied with only using 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/system directory contains a makefile that eases rebuilding the entire
system automatically. To rebuild the entire system simply run:
cd /src/system
make system
This will recompile the entire operating system and install it into the root
directory as it progresses. You will be running a new version of everything upon
completion, except the kernel and programs were previously started will still
be running the old version. 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.
In general, the projects that are part of the core system can be easily built
and installed with the provided makefiles. In general, 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.
### Building 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.
cd /src/libc
make
make install
### Building 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.
cd /src/libm
make
make install
### Building 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 and pong to detect the current resolution and request
whatever resolution they need to function.
cd /src/dispd
make
make install
### Building the 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.
cd /src/utils
make
make install
### Building the 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.
cd /src/bench
make
make install
### Building the Games ###
The games directory contains the source code for the above mentioned games.
These depend on libdispd.
cd /src/games
make
make install
### Building mbrfs ###
The `mbrfs` program creates block devices for every partition in the master boot
record in a block device.
cd /src/mbrfs
make
make install
### Building extfs ###
The `extfs` program translates a block device formatted with the second extended
filesystem and mounts it at an empty directory.
cd /src/extfs
make
make install
### Building mxmpp ###
The program mxmpp is a simple and hacky macro preprocessor. It supports a special
@incude(foo_t.h) directive, which is used to pre-preprocess the headers in the C
library to avoid the overhead of repeated declarations.
cd /src/mxmpp
make
make install
### Building mkinitrd ###
This program produces a Sortix compatible initrd, the file that contains the
initial filesystem used to bootstrap the real root filesystem.
cd /src/mkinitrd
make
make install
### Building the Sortix 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.
cd /src/sortix
make
make install
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.

7
doc/welcome Normal file
View file

@ -0,0 +1,7 @@
Welcome to Sortix!
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.