diff --git a/Makefile b/Makefile index 20f6432b..8ef3cb3e 100644 --- a/Makefile +++ b/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 diff --git a/README b/README index 9494769c..0126100d 100644 --- a/README +++ b/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 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. diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 00000000..dcaf7169 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1 @@ +index.html diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 00000000..46e25bef --- /dev/null +++ b/doc/Makefile @@ -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: diff --git a/doc/cross-development b/doc/cross-development new file mode 100644 index 00000000..b626212f --- /dev/null +++ b/doc/cross-development @@ -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. diff --git a/doc/obsolete-stuff b/doc/obsolete-stuff new file mode 100644 index 00000000..5c1c2599 --- /dev/null +++ b/doc/obsolete-stuff @@ -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. diff --git a/doc/user-guide b/doc/user-guide new file mode 100644 index 00000000..79767912 --- /dev/null +++ b/doc/user-guide @@ -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 ` - change tab size +* `ESC margin ` - add right margin at column +* `ESC popen ` - open command output +* `ESC language ` - 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 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. diff --git a/doc/welcome b/doc/welcome new file mode 100644 index 00000000..57b5f00b --- /dev/null +++ b/doc/welcome @@ -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.