Add documentation.
This commit is contained in:
Jonas 'Sortie' Termansen
parent
184fce3cf3
commit
425069cbf1
15
Makefile
15
Makefile
|
|
@ -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
220
README
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -0,0 +1 @@
|
|||
index.html
|
||||
|
|
@ -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:
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
Loading…
Reference in New Issue