diff --git a/Makefile b/Makefile index e9c1ff5e..40fc945c 100644 --- a/Makefile +++ b/Makefile @@ -157,6 +157,7 @@ sysroot-base-headers: sysroot-fsh .PHONY: sysroot-system sysroot-system: sysroot-fsh sysroot-base-headers + cp -RT share "$(SYSROOT)/share" export SYSROOT="$(SYSROOT)" && \ (for D in $(MODULES); do ($(MAKE) -C $$D && $(MAKE) -C $$D install DESTDIR="$(SYSROOT)") || exit $$?; done) @@ -361,10 +362,7 @@ sortix.iso.xz: $(SORTIX_BUILDS_DIR)/$(BUILD_NAME).iso.xz # Release -$(SORTIX_RELEASE_DIR): - mkdir -p $@ - -$(SORTIX_RELEASE_DIR)/$(VERSION): $(SORTIX_RELEASE_DIR) +$(SORTIX_RELEASE_DIR)/$(VERSION): mkdir -p $@ $(SORTIX_RELEASE_DIR)/$(VERSION)/builds: $(SORTIX_RELEASE_DIR)/$(VERSION) @@ -385,14 +383,6 @@ release-tar: $(SORTIX_RELEASE_DIR)/$(VERSION)/builds/$(BUILD_NAME).tar.xz .PHONY: release-builds release-builds: release-iso.xz release-tar -$(SORTIX_RELEASE_DIR)/$(VERSION)/doc: $(SORTIX_RELEASE_DIR)/$(VERSION) doc doc/* - cp -RT doc $(SORTIX_RELEASE_DIR)/$(VERSION)/doc - rm -f $(SORTIX_RELEASE_DIR)/$(VERSION)/doc/.gitignore - rm -f $(SORTIX_RELEASE_DIR)/$(VERSION)/doc/Makefile - -.PHONY: release-doc -release-doc: $(SORTIX_RELEASE_DIR)/$(VERSION)/doc - $(SORTIX_RELEASE_DIR)/$(VERSION)/README: README $(SORTIX_RELEASE_DIR)/$(VERSION) cp $< $@ @@ -409,10 +399,10 @@ $(SORTIX_RELEASE_DIR)/$(VERSION)/repository/$(HOST): sysroot $(SORTIX_REPOSITORY release-repository: $(SORTIX_RELEASE_DIR)/$(VERSION)/repository/$(HOST) .PHONY: release-arch -release-arch: release-builds release-doc release-readme release-repository +release-arch: release-builds release-readme release-repository .PHONY: release-shared -release-shared: release-doc release-readme +release-shared: release-readme .PHONY: release release: release-arch release-shared diff --git a/README b/README index 4f68dba1..0a44bc87 100644 --- a/README +++ b/README @@ -41,42 +41,25 @@ such as VirtualBox and Qemu: Documentation ------------- -You can find the documentation for Sortix use and development at your local -documentation mirror, for instance: - - The documentation directory in a Sortix system: - /share/doc - - The doc directory inside the Sortix source repository: - doc/ - - The official Sortix website: - https://sortix.org/doc/ +The system is documented as manual pages. Introductory system usage is covered +in the user-guide(7) manual page. Building Sortix --------------- -If you wish to build Sortix under Sortix itself, please consult the user guide: +Development of Sortix under itself is covered in development(7). - $MY_LOCAL_DOCUMENTATION_MIRROR/user-guide +Development from another operating system is covered in cross-development(7). -If you wish to cross-build Sortix from another operating system, please read -the cross development guide: +You can view the cross-development(7) manual page with this command: - $MY_LOCAL_DOCUMENTATION_MIRROR/cross-development - -Documentation -------------- - -Basic usage of the system has been documented at: - - $MY_LOCAL_DOCUMENTATION_MIRROR/user-guide + man share/man/man7/cross-development.7 License ------- Copyright(C) Jonas 'Sortie' Termansen and contributors 2011, -2012, 2013, 2014. +2012, 2013, 2014, 2015, 2016. Sortix is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A diff --git a/doc/Makefile b/doc/Makefile index 10157d9e..42ef20a4 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -5,11 +5,9 @@ include ../build-aux/dirs.mak DOCUMENTS:=\ cross-compilation-sins \ -cross-development \ obsolete-stuff \ porting-guide \ posix-divergence \ -user-guide \ welcome \ all: $(BINARIES) diff --git a/doc/cross-development b/doc/cross-development deleted file mode 100644 index 4ea814aa..00000000 --- a/doc/cross-development +++ /dev/null @@ -1,282 +0,0 @@ -Sortix Cross Development Guide -============================== - -The primary way to build Sortix is on Sortix itself. However, the system may not -be fully up to the task yet and your favorite development environment may not -have been ported. You can cross-compile Sortix from a reasonable similar system -such as GNU+Linux. The build process will liberally use common GNU tool options, -so you may wish to install the basic GNU distribution or compatible. - -Overview --------- - -To build Sortix you need these components: - -* Sortix source tree -* Sortix binutils -* Sortix gcc -* GRUB2 (iso support) -* xorriso (iso support) - -In this tutorial we will cross-compile a Sortix using by following these steps: - -1. Retrieve all the source code. -2. Build additional Sortix-specific tool programs. -3. Create a system root containing all the Sortix system headers. -4. Compile a new compiler that targets Sortix and uses the system root. -5. Actually compile Sortix. - -It is necessary to compile binutils and gcc because your system compilers -doesn't produce executables for Sortix, but rather for your current system. - -Source Code ------------ - -You can find the latest Sortix source code at: -https://gitlab.com/sortix/sortix - -You can find the latest Sortix binutils source code at: -https://users-cs.au.dk/sortie/sortix/toolchain/sortix-binutils-latest.tar.xz - -You can find the latest Sortix gcc source code at: -https://users-cs.au.dk/sortie/sortix/toolchain/sortix-gcc-latest.tar.xz - -It is only possible to build Sortix with this blessed toolchain or a derivative -thereof as it has been customized to understand Sortix and provide a number of -useful extensions. You may need to occasionally upgrade the toolchain, in the -event that it is further modified and Sortix takes advantage of these changes. - -Variables ---------- - -This guide uses shell variables to denote where you have choice. You would -typically decide to set them up somewhat like this: - - # The Sortix source code is in /home/user/sortix - # The cross-compiler is installed in /home/user/opt/x86_64-sortix - - SORTIX_PLATFORM=x86_64-sortix - CROSS_PREFIX=/home/user/opt/x86_64-sortix - SORTIX_SYSROOT=/home/user/sortix/sysroot - export PATH="/home/user/opt/x86_64-sortix/bin:$PATH" - export PATH="/home/user/opt/x86_64-sortix/sbin:$PATH" - -The following sections describe these variables in detail. - -Target Platform ---------------- - -You need to decide what the platform your final Sortix system will run on. You -can currently decide between i486-sortix and x86_64-sortix. In this guide we -will refer to that platform triplet as $SORTIX_PLATFORM. If you want to build -another platform afterwards, then you will have to follow this guide again. - -Cross-Environment ------------------ - -You should install your cross-toolchain into a useful and isolated directory -such as $HOME/opt/$SORTIX_PLATFORM. This allows you to easily dispose of the -directory and keeps it neatly isolated from the rest of the system. Let's refer -to that location as $CROSS_PREFIX. - -You need to add $CROSS_PREFIX/bin and $CROSS_PREFIX/sbin to your $PATH variable: - - export PATH="$CROSS_PREFIX/bin:$PATH" - export PATH="$CROSS_PREFIX/sbin:$PATH" - -This will modify the $PATH variable in this particular shell session. Depending -on your shell and system configuration you can make this permanent by adding -that line to your ~/.profile. Consult your shell documentation. Otherwise type -it in all Sortix-related shells before doing anything. - -Sortix build tools ------------------- - -You need to install some additional Sortix programs into your local environment -as they are needed to build Sortix. Assuming you cloned the Sortix source code -tree into the ~/sortix directory, you can install them by typing the following -commands: - - cd ~/sortix && - make PREFIX="$CROSS_PREFIX" clean-build-tools && - make PREFIX="$CROSS_PREFIX" build-tools && - make PREFIX="$CROSS_PREFIX" install-build-tools && - make distclean - -These tools produce platform independent output so you may wish to install them -into $HOME or /usr/local or where it suits you, and add its bin and sbin to your -$PATH. - -Setting up basic system root ----------------------------- - -The compiler has been taught how to correctly build programs for a Sortix -system, however it gets part of this information from the system headers. The -first step is to create a basic system root that contains the headers and -filesystem structure for the final system. We will install the kernel, libc, -libm, and other core library headers into this directory. Run the following: - - cd ~/sortix && - make sysroot-base-headers HOST=$SORTIX_PLATFORM - -This will automatically set up a basic system root in ~/sortix/sysroot. We will -use this when we build the cross-compiler in a moment. Let's call the system -root directory $SORTIX_SYSROOT. - -Cross-Toolchain Dependencies ----------------------------- - -You may need to install these packages (and their development packages) before -building binutils and gcc, or the packages will refuse to configure or some -obscure error will occur. In particular, you may need to install: - -* Bison -* Flex -* GNU GMP -* GNU MPFR -* GNU MPC - -You should consult the official binutils and gcc documentation on what exactly -you need to install before building these packages yourself. - -Cross-Binutils --------------- - -We need a cross-binutils that have been taught the Sortix program format. If you -have extracted the Sortix binutils source code into ~/src/sortix-binutils then -you can build binutils out-of-directory using these commands: - - mkdir ~/src/binutils-build && - cd ~/src/binutils-build && - ../sortix-binutils/configure \ - --target=$SORTIX_PLATFORM \ - --with-sysroot="$SORTIX_SYSROOT" \ - --prefix="$CROSS_PREFIX" \ - --disable-werror && - make && - make install - -You may need to install some dependencies before you build binutils. You can -remove the temporary ~/src/binutils-build directory when you are done. - -Cross-GCC ---------- - -We need a cross-compiler that has been taught what Sortix is and that supports a -few extensions that have been added to Sortix gcc that isn't present in upstream -gcc. If you have extracted the Sortix gcc source code into ~/src/sortix-gcc then -you can build gcc out-of-directory using these commands. - - mkdir ~/src/gcc-build && - cd ~/src/gcc-build && - ../sortix-gcc/configure \ - --target=$SORTIX_PLATFORM \ - --with-sysroot=$SORTIX_SYSROOT \ - --prefix="$CROSS_PREFIX" \ - --enable-languages=c,c++ && - make all-gcc all-target-libgcc && - make install-gcc install-target-libgcc - -You may need to install some dependencies before you build gcc, such as libmpc, -libmpfr and libgmp. You can remove the temporary ~/src/gcc-build directory when -you are done. Notice how we don't build all of gcc as this isn't possible yet. -For instance, the C++ library requires the Sortix libc to have been built. - -Building Sortix ---------------- - -You now have the needed components to build a working Sortix system. If you have -completed the above steps correctly, then you can simply do: - - cd ~/sortix && - make HOST=$SORTIX_PLATFORM - -This will compile a basic Sortix system into ~/sortix/sysroot with a kernel, -headers, libraries, programs, everything you need. This isn't a bootable system -yet. You need the combination of a kernel and an initrd to boot Sortix. The -initrd is a root filesystem entirely in memory that is loaded by the bootloader -in addition to the kernel. You can generate the initrd in builds/ by running: - - cd ~/sortix && - make HOST=$SORTIX_PLATFORM initrd - -If you want a copy of the kernel and initrd in the current directory (rather -than normally finding them in builds/ and sysroot/), you can run: - - cd ~/sortix && - make HOST=$SORTIX_PLATFORM sortix.bin sortix.initrd - -You now have a sortix.bin and sortix.initrd pair. You can boot Sortix using a -multiboot bootloader by passing them as a multiboot kernel and multiboot -module/initrd. - -If you have xorriso and grub-mkrescue from GRUB 2 installed, then you can -can build a bootable .iso by typing: - - cd ~/sortix && - make HOST=$SORTIX_PLATFORM sortix.iso - -This will produce a sortix.iso file that is bootable on real hardware and -virtual machines. This works by first building Sortix system and packaging up an -initrd, then it create a cdrom image with a bootloader configured to load the -kernel and initrd stored on the cdrom. If the command fails, see below. - -You can clean the source directory fully: - - cd ~/sortix && - make distclean - -This will clean all the source directories and ports and delete all the builds -and the binary package repositories (if you use ports as below) and it will -delete the system root containing your installed system. Alternatively, you may -be interested in the target `mostlyclean `that doesn't delete binary packages -for ports, as they may take considerable time to recompile. See also the targets -`clean`, `clean-core`, `clean-sysroot`, `clean-repository`, `clean-builds`, -and `clean-ports` which lets you control what is cleaned. - -Building Ports --------------- - -You can extend your Sortix system with third party software that has been ported -to Sortix. You can find the suitable ports if you visit the download directory -for this release and enter the subdirectory `srctix` which contains compressed -archived source tixes. Each such file is simply a compressed tarball that -contains a single directory with the source code for this port. If you have the -file `libfoo.srctix.tar.xz`, you can extract it into ~/sortix/ports as such: - - cd ~/sortix && - mkdir -p ports && - cd ports && - tar --extract --file $HOME/Downloads/libfoo.srctix.tar.xz - -This will create the directory `~/sortix/ports/libfoo` that contains the source -code for the libfoo port. Keep in mind that many ports depends on another more -basic ports and you will need to satisfy the dependencies. The build process -will give an error and tell you which dependency was missing if you haven't -satisfied the dependencies. Other ports have optional dependencies which gives -an inferior installation if the dependencies are not satisfied. - -If you have installed the Tix package management (which is done by the -`make install-build-tools` command above), then the top-level makefile will -automatically detect all the installed ports. They will automatically be built -along with the core system the next time you build Sortix and is present in -your initrd and bootable images. - -For more information on ports and how they work, please read: - - $MY_LOCAL_DOCUMENTATION_MIRROR/porting-guide - -Building some ports may require additional tools to be installed on your system -and other unforeseen problems may arise that means the port doesn't compile -properly on your system. Should a port fail to compile, then the `tix-build` -command will offer you a chance to investigate the situation in a shell. - -Troubleshooting ---------------- - -If producing a bootable cdrom with grub-mkrescue gives the error - - xorriso : FAILURE : Cannot find path '/efi.img' in loaded ISO image - -then your GRUB grub installation is defective. You need to install mformat(1) to -use grub-mkrescue. diff --git a/doc/user-guide b/doc/user-guide deleted file mode 100644 index c9ce311d..00000000 --- a/doc/user-guide +++ /dev/null @@ -1,580 +0,0 @@ -Sortix User Guide -================= - -Thanks for your interest in Sortix! This document will describe how to use it -and what features are available. Sortix is a small self-compiling Unix-like -Operating System developed since 2011. The system is free software licensed -under the GNU General Public License and other licenses. - -Introduction ------------- - -If you are using a Sortix live medium or a prebuilt harddisk image, you will -likely be met with a bootloader. Normally, GNU GRUB is used as the Sortix -bootloader. In that case, simply pick Sortix from the boot menu. If you have -installed Sortix manually, you will have to configure your bootloader to boot -Sortix. - -The bootloader will then load the Sortix kernel and start the system. The -initialization process will spawn a shell shortly. The command line is similar -to those of Unix systems and many common Unix commands are available. - -Keyboard Layout ---------------- - -The kernel translates the raw keyboard scancodes into unicode codepoints using -the current keyboard layout table associated with the terminal. Such layout -tables are compiled from a textual description into compressed binary tables -using the `kblayout-compiler` program. The kernel has a default US keyboard -layout integrated into it at compile time. - -You can change the current keyboard layout using the `chkblayout` program. It -loads a keyboard layouts with the requested name from the `/share/kblayout` -directory, or a user-supplied file if the path contains a slash. The system -comes with a few existing keyboard layouts and more can be added if desired. - -* `dk' -* `us' - -You can select a particular keyboard layout by typing something like: - - chkblayout da_DK - -Mind that while the user-space programs and the kernel all handle text correctly -as unicode, your console may not be able to render such code points. VGA text -mode consoles, for instance, only has the VGA font available, which contains -just codepage 437 characters. The console driver helpfully translates some -unicode characters that look like codepage 437 characters into their lookalikes -for rendering. The graphical kernel console reuses the VGA font internally, but -has no hardware restrictions. In principle, support could be added such that -user-space can upload font data to the kernel graphical console. - -Changing the Video Mode ------------------------ - -After boot, the screen resolution will be default be in VGA text mode. This only -allows 80 columns and 25 rows of 16 color ASCII text. Naturally, this is very -limited but works on most systems. - -You can change the display resolution using the `chvideomode` program. However, -you need a suitable kernel driver to do the mode setting. The current release -only has a simple BGA driver, which works in virtual machines such as Qemu, -VirtualBox or Bochs. - -The BGA driver can support virtually any resolution, but since the interface -fails to report which resolutions are appropriate in the current context, I have -simply hard-coded whatever resolutions I found reasonable when I wrote it. - -Powering Off ------------- - -Unless you are using a harddisk image or your initrd has been specially -configured to mount a permanent root filesystem, then this environment is -entirely temporary. You will loose all modifications when powering off the -current system. - -The system automatically reboots when the initial shell exits. You can exit the -current shell by entering `exit`, which if entered from the initial shell will -reboot the entire system (losing any changes if the root filesystem is not -permanent). Additionally, you can press Control-D ('^D') to exit the current -shell, but the initial shell will require you to enter a literal `exit` before -it exits and the system reboots. - -The init process will restart the shell in the event that it crashes or dies -from a signal. You can use the `kill $$` command to kill the current shell, and -if it is the initial shell, you will get a new shell. - -More Documentation ------------------- - -The system documentation (at least what has been documented so far) is installed -in the `/share/doc` directory. You can view these documents (well, the ones that -are plain text, there is no `man` program yet) using the `editor` program, which -you exit by pressing Control-Q ('^Q'). It is probably a good idea to change -the resolution using the `chvideomode` program if drivers are available. - -If your release contains third party software, then this directory may also -contain documentation for this software, which may or may not be easily -viewable using the editor. - -Filesystem Structure --------------------- - -This as an incomplete list of the common top level directories in Sortix. - -* `/bin` - Programs. -* `/boot` - Kernel images, initrd images. -* `/dev` - Device filesystem. -* `/etc` - System-wide configuration. -* `/home` - User directories. -* `/include` - Header files. -* `/libexec` - Non-user programs. -* `/lib` - Shared libraries. -* `/root` - Directory of the root user. -* `/share` - Architecture independent files. -* `/share/doc` - Documentation. -* `/share/kblayout` - Keyboard layouts. -* `/src` - System source code. -* `/tmp` - Temporary files. - -Some of these directories not be present or empty on your installation. - -Using the Shell ---------------- - -Sortix features a homemade shell, which at best can be described as hacky. -Despite that, it does have some key features. Here are the features that are -supported: - -* Processes can be started in the usual Unix manner. -* Tab-completion. -* Line editing. -* History. -* Background tasks ('&'). -* Standard redirection ('<', '>', '>>'). -* Piping stdout from a task to stdin of another ('|'). -* Stopping the currently running task (Control-C, '^C'). -* Waiting for a task to complete and executing the next (';'). -* Setting environmental variables ('FOO=bar'). -* Using $FOO to insert an environmental variable. -* Listing all environmental variable ('env'). -* Changing the current directory ('cd /home'). -* Removing an environmental variable ('unset FOO'). -* Clearing all enviromental variables ('clearenv'). -* Executing shell scripts ('sh script.sh param1 param2'). -* Escaping some special characters ('\'). -* Comments ('#'). -* Exiting the shell ('exit') ('exit 42'). -* Basic wildcards ('foo*.bar'). -* Clearing the screen (Control-L, '^L'). -* Deleting the last typed word (Control-W, '^W'). -* Deleting everything before the cursor (Control-U, '^U'). -* Deleting everything after the cursor (Control-K, '^K'). -* Go to start of line (Control-A, '^A', Home). -* Go to end of line (Control-E, '^E', End). -* Move between words (Control-arrows). -* Quotes (''') ('"'). - -These features are missing from the shell: - -* Proper recursive shell grammar parsing. -* Heredoc sequences. -* Command substitution ('$(ls)', '`ls`'). -* Arithmetic expansion ('$((2 + 2))'). -* Aliases. -* Conditions and loops ('if', 'case', 'while', 'until', 'for'). -* Functions. -* Some special parameters ('$@', '$*', '$#', '$-', '$!). -* Special shell variables ('$ENV', '$IFS', '$LINENO'). -* Shell prompt customization ('$PS1', '$PS2', '$PS4'). -* Tilde expansion ('~/foo'). -* Any but the simplest variant of Parameter Expansion. -* Proper shell wildcard support ('*/*.foo'). -* Ability for variables to not be exported. -* Export keyword ('export FOO', 'export BAR=bar'). -* Subshells. -* Proper redirection to/from specific file descriptors. -* And much more; the shell remains hacky. - -If a better shell is installed, and the shell is non-interactive, then the sh -program will automatically run the superior shell transparently. - -Included Programs ------------------ - -Sortix comes with a number of home-made programs. Here is an overview: - -* `asteroids` - remake of the classic asteroids game -* `basename` - strip directory from filenames -* `benchctxswitch` - useless benchmark -* `benchsyscall` - slightly less useless benchmark -* `carray` - convert a binary file to a C array -* `cat` - display file on terminal -* `chkblayout` - change keyboard layout -* `chmod` - change file mode bits -* `chroot` - change the root directory -* `chvideomode` - change display resolution -* `clear` - clear terminal -* `colormake` - colorful version of make (if make is available) -* `column` - format lines nicely in columns -* `cp` - copy file -* `date` - display current time and date -* `df` - report file system disk space usage. -* `dirname` - strip last component from file name -* `dispd` - non-existent display server -* `du` - report file and directory disk usage -* `echo` - print command line arguments -* `editor` - text editor -* `env` - run a program in a modified environment -* `expr` - evaluate expressions -* `extfs` - ext2 filesystem server -* `false` - exit with an error status -* `find` - recursively list files -* `head` - display start of file -* `help` - show list of available programs -* `id` - print real and effective user and group IDs -* `init` - system management deamon -* `initrdfs` - tool for examining initrds -* `install` - installs a program into a system directory -* `kernelinfo` - display kernel information -* `kill` - send signal to process -* `ln` - create filesystem links -* `ls` - list contents of directory -* `mbrfs` - create partitions for master boot record block device -* `memstat` - print memory information -* `mkdir` - create directory -* `mkinitrd` - create an initrd -* `mktemp` - create temporary file or directory -* `mv` - move a file -* `pager` - display file page by page -* `ps` - report a snapshot of the current processes -* `pstree` - display a tree of processes -* `pwd` - print current directory path -* `realpath` - canonicalize filesystem paths -* `regress` - run system tests -* `rm` - remove file -* `rmdir` - remove empty directory -* `sh` - command shell -* `sleep` - delay for a specified amount of time -* `sort` - sort lines of text files -* `stat` - display file status -* `tail` - display end of file -* `time` - measure program running time -* `trianglix` - triangle system -* `tr` - translate, squeeze and/or delete characters -* `true` - exit with a success status -* `type` - type raw characters directly into the terminal -* `uname` - system information -* `uniq` - report or omit repeated lines -* `unmount` - unmount filesystem -* `uptime` - time since initialization -* `wc` - count words and lines -* `which` - find path to command -* `yes` - repeatedly output a line - -Third Party Software --------------------- - -In addition, a selection of third-party software has been ported and may be -present on your installation. In particular, the following software packages are -known to work at some level of stability: - -* binutils -* bison -* bochs -* bzip2 -* dash -* diffutils -* gawk -* gcc -* gettext (GNU) -* git -* grep (GNU) -* groff -* gzip (GNU) -* hello (GNU) -* libassuan -* libatk -* libav -* libcairo -* libdaala -* libdbus -* libexpat -* libffi -* libfontconfig -* libfreetype -* libgcrypt -* libgdk-pixbuf -* libglib -* libGL (Mesa) -* libgmp -* libgnutls -* libgpg-error -* libgtk -* libharfbuzz -* libiconv -* libjpeg -* libksba -* libmpc -* libmpfr -* libnettle -* libogg -* libpango -* libpixman -* libpng -* libSDL -* libssl (LibreSSL) -* libstdc++ -* libtheora -* libvorbis -* libwayland -* libxkbcommon -* libz (Sortix) -* m4 (GNU) -* make (GNU) -* patch (GNU) -* python -* quake -* sed (GNU) -* tar (GNU) -* xz -* (and more) - -More software will be ported in the future as the system matures. Your release -may not contain all the ported software because of disk space constraints or -the stability/usefulness of the package or the difficulty to build. - -Included Games --------------- - -The system comes with a number of small casual games. Note that some games -require running in the correct display mode before they will function. - -### Asteroids ### - -Mine for crystals in an asteroid field! Start the `asteroids` program and if you -have the needed driver support, you can explore space in a gloriously rendered -asteroid field of bitmap graphics. Use the arrow keys to navigate. Avoid the -white asteroids as they will destroy your space ship. Use the `space` key to -fire a laser beam that breaks the asteroid apart, but beware that the fragments -will accelerate. Alternatively, use the `Left Control` key to shoot a fireworks -of laser beams, but it doesn't reach as far and may split a big asteroid into -many small dangerous asteroids. Your goal is to collect as many blue crystals as -possible without dying. You can use the `B` key to spawn a bot that will -cluelessly follow you and shoot whatever asteroids it deems dangerous. You can -use the `A` key to spawn a black hole (or just a big attracting thing). - -System Source Code ------------------- - -The entire system source code (except third party components) is installed into -the `/src` directory. You can use the `editor` program to view and edit the -system source code. If your release contains the GNU compiler collection (gcc), -you can even modify the system and compile custom programs. - -Editing Files -------------- - -You can use the `editor` program to edit files. The editor itself is fairly -simple to use. It currently supports these keyboard commands: - -* `Ctrl-C` - Copy -* `Ctrl-I` - Go to line -* `Ctrl-K` - Cut -* `Ctrl-O` - Open a file -* `Ctrl-Q` - Exit -* `Ctrl-S` - Save a file -* `Ctrl-V` - Paste -* `Ctrl-X` - Cut -* `ESC language ` - enable syntax highlighting -* `ESC line-numbering ` - enable line numbering -* `ESC margin ` - add right margin at column -* `ESC popen ` - open command output -* `ESC tabsize ` - change tab size - -It is not currently possible to port third party editors because the terminal -implementation is not standards-compliant enough and is seriously lacking. - -Partitions ----------- - -If the initialization code didn't automatically create block devices for your -partitions, but the harddisk block device itself is supported, you can use the -`mbrfs` program to create block devices for the partitions. - - mbrfs /dev/ata0 - -The program will output the names of the new block devices. - -Mounting Filesystems --------------------- - -The `extfs` filesystem server translates a block device formatted with the -second extended filesystem and mounts it at an empty directory. The filesystem -may need to be carefully configured as not all ext2 features are currently -supported. In particular, only the `large_file` and `filetype` features are -supported. There is no support for formatting or checking filesystems yet, this -will have to be done from an external system. If the device `/dev/ata0p1` -contains an ext2 filesystem, then it can be mounted using: - - mkdir /mnt - extfs /dev/ata0 /mnt - -You can then access the filesystem at `/fs`. You can unmount it safely when you -are done using it: - - unmount /mnt - -This will safely shut down the filesystem process and sync to disk. Beware how -init doesn't know about your personal mount points and powering off the system -will cause all processes to be destroyed, and such mount points will not be -shut down gracefully at the moment. - -Graphical User Interface ------------------------- - -The `dispd` display server is still under development. Sortix does not feature -any documented graphical user interface at the moment. - -Sortix comes with the orthogonal graphical multi-user revolutionary triangle -system Trianglix, an attempt at making the most foreign yet somehow usable user -interface. You just need to run `trianglix` to start it. - -Network -------- - -Network support is still under development and is not documented at this point. -Unix sockets are available. - -Building Sortix under Sortix ----------------------------- - -You can build Sortix under itself and make modifications to it. It is not yet -possible to build all the the third party software used to build itself, but you -can use the system to improve it until it is possible to build third party -software under it. - -You need a version of Sortix that ships its own source code in `/src` and -contains a copy of the GNU Compiler Collection (gcc). Additionally, you should -be booting from a harddisk so that the new kernel is used after a reboot. -Otherwise you can only update to a new user-land. - -You can use the `colormake` program instead of regular `make` if you want -colored output, which eases spotting compile warnings and errors. This program -simply invokes the real `make` and colors its output. - -The `/src` directory contains a makefile that eases rebuilding the entire system -automatically. To rebuild the entire system simply run: - - cd /src - make - chroot /src/sysroot init # to test the new user-land - make sysmerge # to update to the new user-land - -This will recompile the entire operating system and install it into the staging -area `/src/sysroot`. This is a full usable image of the root filesystem for a -Sortix installation and you can chroot into it if desired. - -The sysmerge target merges the image in `/src/sysroot` onto the current root -filesystem without changing local files, as opposed to a make install that -indiscriminately overwrites everything. - -You will be running a new version of everything upon completion, except the -kernel and existing processes will continue to run the old programs. If the root -filesystem is permanent and the computer has been configured to boot from it, -then you can reboot the system by exiting the initial shell. You will then be -running an entirely new system. - -### Building System Components ### - -The projects that are part of the core system can be easily built and installed -with the provided makefiles. They can be built with this simple sequence: - - cd /src/${package} - make - make install - -If you wish to install the package somewhere than the default location, you can -use the `PREFIX` (and, depending on your needs, `EXEC_PREFIX`, `BINDIR`, -`LIBDIR`, ...) environmental variable to specify where the program will be -installed: - - make PREFIX=/local - make PREFIX=/local install - -Additionally, should you require that the package should be installed into a -temporary location before it is fully installed, use the `DESTDIR` environmental -variable: - - make PREFIX=/local - make PREFIX=/local DESTDIR=/temporary-location - -This will effectively install the package into `/temporary-location/local`, but -the package will expect that it is installed into `/local` when it is run. This -is useful for package management purposes to capture a copy of all the installed -files before they are installed for real. - -### The C library ### - -The C library (libc) implements the common functions, data types and constants -required by the C programming language standard, POSIX, other standards, and -various Sortix-specific extensions. Most programs for Sortix directly or -indirectly rely on this core library for basic functionality and system calls. -The build process builds a regular user-space C library as well as a -freestanding C library designed for inclusion into the Sortix kernel. After -rebuilding the C library, you may wish to rebuild the entire user-land since -those programs have an older libc version statically linked into them. - -### The Math Library ### - -The Math Library (libm) provides useful mathematical functions for manipulating -floating-point numbers of various sizes. This implements the header as -known from standard C. Like the C library, you will likely want to recompile -large parts of user-land if you update this library. - -### The Pthread Library ### - -The Pthread Library (libpthread) provides a threading implementation through the -standard header as known from POSIX. Like the C library, you will -likely want to recompile large parts of user-land if you update this library. - -### The Display Daemon ### - -The dispd library allows processes to communicate with the dispd server that -handles window management and graphical output. Currently, there is no such -server and the library calls the kernel interface itself. This library allows -games such as asteroids to detect the current resolution and request whatever -resolution they need to function. - -### Utility Collection ### - -The utility collection contains common programs such as `ls`, `cp`, `mkdir` and -more. These programs allow the basic operation from the command line. - -### Benchmarks ### - -The system comes with some small and outdated benchmark programs. They don't -currently give any meaningful values, so you should not use them for anything. - -### Games ### - -The games directory contains the source code for the above mentioned games. -These depend on libdispd. - -### mbrfs ### - -The `mbrfs` program creates block devices for every partition in the master boot -record in a block device. - -### extfs ### - -The `extfs` program translates a block device formatted with the second extended -filesystem and mounts it at an empty directory. - -### mkinitrd ### - -This program produces a Sortix compatible initrd, the file that contains the -initial filesystem used to bootstrap the real root filesystem. - -### regress ### - -This is a collection of operating system test cases run using the `regress` -driver program. - -### carray ### - -This program converts a binary file to an C array. - -### sh ### - -This is the Sortix shell. Currently the `sh` program is a wrapper that looks for -a better non-interactive shell if running a script, otherwise it invokes the -hacky `sortix-sh` program. - -### Kernel ### - -The Sortix kernel is the core of the Sortix operating system. It provides all -the primitives libc needs to implement a Unix-like environment. - -Note that you need to reboot the system to use the new kernel and that you need -a permanent root filesystem or your local changes will be lost. diff --git a/doc/welcome b/doc/welcome index 57b5f00b..a3fa49af 100644 --- a/doc/welcome +++ b/doc/welcome @@ -1,7 +1,3 @@ -Welcome to Sortix! +You can view the documentation for new users by typing: -You can view the documentation for new users in the editor by typing: - - editor /share/doc/user-guide - -Press Control-Q (^Q) to quit the editor. + man user-guide diff --git a/share/man/man5/hostname.5 b/share/man/man5/hostname.5 new file mode 100644 index 00000000..666ceb2b --- /dev/null +++ b/share/man/man5/hostname.5 @@ -0,0 +1,29 @@ +.Dd $Mdocdate: October 5 2015 $ +.Dt HOSTNAME 5 +.Os +.Sh NAME +.Nm hostname +.Nd initial hostname +.Sh SYNOPSIS +.Nm /etc/hostname +.Sh DESCRIPTION +The +.Nm hostname +file is read on boot by +.Xr init 8 +and is used as the system hostname. No hostname is set if the file is missing +and the hostname remains the kernel default. +.Sh FORMAT +The file must contain a valid hostname and no whitespace on a single line. +.Sh FILES +.Bl -tag -width "/etc/hostname" -compact +.It Pa /etc/hostname +System hostname. +.El +.Sh EXAMPLES +.Bd -literal +dragon +.Ed +.Sh SEE ALSO +.Xr sethostname 2 , +.Xr init 8 diff --git a/share/man/man5/kblayout.5 b/share/man/man5/kblayout.5 new file mode 100644 index 00000000..ffe771e3 --- /dev/null +++ b/share/man/man5/kblayout.5 @@ -0,0 +1,43 @@ +.Dd $Mdocdate: October 5 2015 $ +.Dt KBLAYOUT 5 +.Os +.Sh NAME +.Nm kblayout +.Nd initial keyboard layout +.Sh SYNOPSIS +.Nm /etc/kblayout +.Sh DESCRIPTION +The +.Nm kblayout +file is read on boot by +.Xr init 8 +and names a file in +.Pa /share/kblayout +that is loaded and set as the keyboard layout. The default kernel US keyboard +layout is retained if the file is missing. +.Pp +The kernel translates the raw keyboard scancodes into unicode codepoints using +the keyboard layout table associated with the terminal. Keyboard layout +tables are compiled from a textual description with +.Xr kblayout-compiler 1 +into compressed binary tables. +.Sh FORMAT +The file must contain a filename of +.Pa /share/kblayout +on a single line. +.Sh FILES +.Bl -tag -width "/share/kblayout" -compact +.It Pa /etc/kblayout +Name of initial keyboard layout. +.It Pa /share/kblayout +Keyboard layouts. +.El +.Sh EXAMPLES +.Bd -literal +dk +.Ed +.Sh SEE ALSO +.Xr chkblayout 1 , +.Xr kblayout-compiler 1 , +.Xr tcsetblob 2 , +.Xr init 8 diff --git a/share/man/man7/cross-development.7 b/share/man/man7/cross-development.7 new file mode 100644 index 00000000..d17fe4da --- /dev/null +++ b/share/man/man7/cross-development.7 @@ -0,0 +1,244 @@ +.Dd $Mdocdate: December 29 2015 $ +.Dt CROSS-DEVELOPMENT 7 +.Os +.Sh NAME +.Nm cross-development +.Nd operating system development from another operating system +.Sh DESCRIPTION +The +.Xr development 7 +manual pages describes the primary way of building the operating system, which +is under itself. The secondary way is to cross-compile it from a sufficiently +similar operating system such as Linux with the GNU tools installed. The build +system assumes the presence of some GNU extensions in the standard command line +tools. This document will detail the process of bootstrapping a Sortix system +from another operating system. +.Ss Overview +To build Sortix you need these components: +.Bl -bullet -compact +.It +Sortix source code +.It +Sortix binutils +.It +Sortix gcc +.It +GRUB (for iso creation) +.It +xorriso (for iso creation) +.El +.Pp +The overall process is: +.Bl -bullet -compact +.It +Retrieving all the source code. +.It +Installing the build tools. +.It +Creating a system root with the system headers. +.It +Creating a cross-compiler. +.It +Cross-compiling the operating system. +.El +.Ss Source Code +You can find the latest Sortix source code at +.Lk https://sortix.org/source/ +.Pp +You can find the latest Sortix binutils source code at +.Lk https://sortix.org/toolchain/sortix-binutils-latest.tar.xz +.Pp +You can find the latest Sortix gcc source code at +.Lk https://sortix.org/toolchain/sortix-gcc-latest.tar.xz +.Pp +This is a compiler toolchain that has been modified to support Sortix. The +toolchain is sometimes updated and you will need the latest toolchain to keep +building the latest code. +.Ss Variables +This document will use shell variables to denote where you have choice. You +would typically set them up like this: +.Bd -literal + # The Sortix source code is in /home/user/sortix + # The cross-compiler is installed in /home/user/opt/x86_64-sortix + SORTIX_PLATFORM=x86_64-sortix + CROSS_PREFIX=/home/user/opt/x86_64-sortix + SORTIX_SYSROOT=/home/user/sortix/sysroot + export PATH="/home/user/opt/x86_64-sortix/bin:$PATH" + export PATH="/home/user/opt/x86_64-sortix/sbin:$PATH" +.Ed +.Pp +The following sections describe these variables in detail. +.Ss Target Platform +You need to decide what the platform your final Sortix system will run on. You +can currently decide between +.Sy i486-sortix +and +.Sy x86_64-sortix . +In this guide we will refer to that platform triplet as +.Ev SORTIX_PLATFORM . +If you want to build another platform afterwards, then you will have to follow +this guide again. +.Ss Cross-environment +You should install your cross-toolchain into a useful and isolated directory +such as +.Pa $HOME/opt/$SORTIX_PLATFORM . +This allows you to easily dispose of the directory and keeps it isolated from +the rest of the system. We'll refer to that location as +.Ev CROSS_PREFIX. +.Pp +You need to add +.Pa $CROSS_PREFIX/bin +and +.Pa $CROSS_PREFIX/sbin +to your +.Ev PATH +variable: +.Bd -literal + export PATH="$CROSS_PREFIX/sbin:$CROSS_PREFIX/bin:$PATH" +.Ed +.Pp +This will modify the +.Ev PATH +variable in this particular shell session. You can make this permanent by +adding that line to your +.Pa ~/.profile +or the applicable file for your shell and system. Consult your shell +documentation. Otherwise type it in all Sortix-related shells before doing +anything. +.Ss Build Tools +You need to install some additional build tools as they are needed to build the +operating system. The installed build tools must be in sync with the source +code as described in +.Xr development 7 . +Assuming the source code is in +.Pa ~/sortix , +you can install them by running: +.Bd -literal + cd ~/sortix && + make PREFIX="$CROSS_PREFIX" clean-build-tools && + make PREFIX="$CROSS_PREFIX" build-tools && + make PREFIX="$CROSS_PREFIX" install-build-tools && + make distclean +.Ed +.Pp +These tools produce platform independent output so you may wish to install them +into +.Pa $HOME/bin +and +.Pa $HOME/sbin +or +.Pa /usr/local/bin +and +.Pa /usr/local/sbin +or where it suits you in your +.Ev PATH . +.Ss System Root with System Headers +Building the compiler requires the standard library headers being available. +This can be satisfies by creating a system root with the system headers: +.Bd -literal + cd ~/sortix && + make sysroot-base-headers HOST=$SORTIX_PLATFORM +.Ed +.Pp +This will create a system root at +.Pa ~/sortix/sysroot . +Refer to that directory as +.Ev SORTIX_SYSROOT . +.Ss Cross-toolchain Dependencies +You need to install these libraries (and the development packages) before +building binutils and gcc: +.Bl -bullet -compact +.It +bison +.It +flex +.It +libgmp +.It +libmpfr +.It +libmpc +.El +.Pp +Consult the official binutils and gcc documentation for the exact dependencies. +.Ss binutils +Assuming you extracted the binutils to +.Pa ~/src/sortix-binutils , +you can build binutils out-of-directory by running: +.Bd -literal + mkdir ~/src/binutils-build && + cd ~/src/binutils-build && + ../sortix-binutils/configure \\ + --target=$SORTIX_PLATFORM \\ + --with-sysroot="$SORTIX_SYSROOT" \\ + --prefix="$CROSS_PREFIX" \\ + --disable-werror && + make && + make install +.Ed +.Pp +You can remove the temporary +.Pa ~/src/binutils-build +directory when finished. +.Ss gcc +Assuming you extracted the gcc to +.Pa ~/src/sortix-gcc , +you can build gcc out-of-directory by running: +.Bd -literal + mkdir ~/src/gcc-build && + cd ~/src/gcc-build && + ../sortix-gcc/configure \\ + --target=$SORTIX_PLATFORM \\ + --with-sysroot="$SORTIX_SYSROOT" \\ + --prefix="$CROSS_PREFIX" \\ + --enable-languages=c,c++ && + make all-gcc all-target-libgcc && + make install-gcc install-target-libgcc +.Ed +.Pp +You can remove the temporary +.Pa ~/src/gcc-build +directory when finished. Notice how special make targets are used to not build +all of gcc. +.Ss Building Sortix +With the build tools and cross-compiler in the +.Ev PATH +is it now possible to build the operating system as described in +.Xr development 7 +by setting +.Ev HOST +to your value of +.Ev SORTIX_PLATFORM . +This tells the build system you are cross-compiling and it will run the +appropriate cross-compiler. For instance, to build an bootable cdrom image +using a +.Sy x86_64-sortix +cross-compiler you can run: +.Bd -literal + cd ~/sortix && + make HOST=x86_64-sortix sortix.iso +.Ed +.Pp +This creates a bootable +.Pa sortix.iso . +See the +.Xr development 7 +manual page for how to use the build system. +.Ss Troubleshooting +If producing a bootable cdrom with +.Xr grub-mkrescue 1 +gives the error +.Pp +.Dl xorriso : FAILURE : Cannot find path '/efi.img' in loaded ISO image +.Pp +then your GRUB installation is defective. You need to install +.Xr mformat 1 +to use +.Xr grub-mkrescue 1 +in your case. +.Sh SEE ALSO +.Xr make 1 , +.Xr development 7 , +.Xr installation 7 , +.Xr porting-guide 7 , +.Xr sysinstall 8 diff --git a/share/man/man7/development.7 b/share/man/man7/development.7 new file mode 100644 index 00000000..52f49a93 --- /dev/null +++ b/share/man/man7/development.7 @@ -0,0 +1,258 @@ +.Dd $Mdocdate: December 29 2015 $ +.Dt DEVELOPMENT 7 +.Os +.Sh NAME +.Nm development +.Nd operating system development instructions +.Sh SYNOPSIS +.Pa /src +.Sh DESCRIPTION +Releases come with the system source code in +.Pa /src . +It can be modified, compiled and installed on the current system. +The source code is built with a +.Xr make 1 +build system. The source code can be located in any location, if so, simply +substitute +.Pa /src +with the real location. These instructions only apply to building the operating +system from within itself, those building it from another operating system needs +to follow +.Xr cross-development 7 +instead. +.Pp +If you are building a new version of the operation system where build tools have +been added or changed, you first need to install the new tools. This is not +needed when building the matching release. To do so, run as root: +.Bd -literal + cd /src + make distclean # fully clean build directory + make install-build-tools # install new tools + make clean-build-tools # clean for real build below +.Ed +.Pp +To build the base operating system and upgrade the current +system, run as root: +.Bd -literal + cd /src + make # build new operating system in /src/sysroot + make sysmerge # upgrade current operating system with /src/sysroot +.Ed +.Pp +The build system creates a minimal root filesystem structure in the +.Pa /src/sysroot +and builds each operating system component in turn, installing them into the +sysroot. If the source code for ports are placed in +.Pa /src/ports +then they are automatically built as well. The result is a minimal system that +can be turned into working system by adding important configuration such as +.Xr passwd 5 . +.Pp +The +.Sy sysmerge +make target ensures a system is built in +.Pa /src/sysroot +and then uses it to replace the current operating system. It ignores +configuration files and other things that could cause conflicts when merging +with an existing system. The new user-space is running on completition, though +existing processes will be running the old programs. Likewise a reboot is needed +to run the new kernel. +.Ss Root Makefile +The +.Pa /src/Makefile +handles the high level build of the operating system. The important targets +are: +.Bl -tag -width "12345678" +.It Sy all +(default) Build each component in turn and install them into the sysroot. +.It Sy build-tools +Make all build tools. +.It Sy clean +Clean the component directories and the port source code. +.Sy ( clean-core, clean-ports ) +.It Sy clean-build-tools +Clean the directories of all build tools. +.It Sy distclean +Run every clean target such that the source code is ready for distribution. +.Sy ( clean-builds, clean-core, clean-ports, clean-release, clean-repository, clean-sysroot ) +.It Sy install-build-tools +Install all build tools after making them. +.It Sy iso +Create a release iso in the +.Pa /src/builds +directory after making +.Sy all . +.It Sy mostlyclean +Clean everything except binary packages. +.Sy ( clean-builds, clean-core, clean-ports, clean-release, clean-sysroot ) +.It Sy release +Make +.Sy iso +and construct release directory tree in +.Pa /src/release +suitable for online publishing. +.It Sy sortix.iso +Make +.Sy iso +and place it in the current directory as +.Pa sortix.iso . +.It Sy sysmerge +Upgrade the current operating system using the sysroot after making the +.Sy all +target. +.It Sy sysroot-base-headers +Create the sysroot and install only the headers of the standard library and +kernel into it. This is useful when bootstrapping the runtime libraries of the +compiler that need to know about libc prior to building libc. +.El +.Pp +The important environment variables influencing the Makefile are: +.Bl -tag -width "12345678" +.It Ev BUILD +The platform of the current operating system. This defaults to the current machine +and operating system. +.It Ev HOST +Specifies platform on which the compiled code will run. This defaults to the +current machine and operating system. This is used when cross-compiling the +operating system. When cross-compiling the operating system, it must be set to +one of +.Sy i486-sortix +and +.Sy x86_64-sortix . +This must be unset when building the build tools as they run on the current +operating system. The compiler tools are prefixed with this variable if it does +not match +.Ev BUILD. +.It Ev OPTLEVEL +Specifies compiler optimization options that gets added to +.Ev CFLAGS +and +.Ev CXXFLAGS . +.El +.Ss Components +The operating systems components, such as libc and the kernel, each have their +own directory by that name. It contains a makefile that can build and install +that component. This allows building and installing only that component onto +the current operating system. +.Pp +For instance, to build and install libc, run as root: +.Bd -literal + cd /src/libc + make + make install +.Ed +.Pp +System libraries are statically linked and you will have to relink programs with +the new library for changes to take effect. Building the whole operating system +from the root makefile ensures components are built in the right order such that +all programs use fresh libraries. +The root makefile invokes component makefiles with +.Ev SYSROOT +set to +.Pa /src/sysroot +to force the compiler to locate files there. Likewise when installing, it sets +.Ev DESTDIR +to +.Pa /src/sysroot +to make it install files there. +.Ss Directories +In addition to the directories for each operating system component, there are +these special directories: +.Bl -tag -width "12345678" +.It Pa /src/ports +If this directory exists, each subdirectory can contain the source code for a +port that gets built along with the rest of the system. +.It Pa /src/release +The +.Sy release +root makefile target creates this directory and populates it with a directory +structure suitable for online publishing of a release. +.It Pa /src/repository +If ports are present, this directory is made when binary packages are built and +they are stored here. This works as a cache so ports don't have to be rebuilt +every time the operating system is. Packages are also copied from here rather +than the sysroot when making releases. +.It Pa /src/sysroot +This directory is made when building the operating system and the freshly made +files are installed here. The build system uses this as the system root which +forces the compiler to look here for headers and libraries. This ensures a +clean bootstrap where files from the current operating system do not leak into +the new system. +.It Pa /src/sysroot-overlay +If this directory exists, it is added to the initrd of the produced iso and can +contain additional system files. +.El +.Ss Build Tools +Some components are used to build the source code and must match the versions +in the source code being built. These are currently: +.Pp +.Bl -bullet -compact +.It +carray +.It +kblayout-compiler +.It +mkinitrd +.It +tix +.El +.Pp +If the currently installed versions of those tools are older than the ones in +the source code, you must update them. The +.Sy clean-build-tools +root makefile target cleans the applicable directories, the +.Sy build-tools +root makefile target builds them from the source code, and the +.Sy install-build-tools +root makefile target installs the new version. You must clean the compiled +files from the source code afterwards because the compiled tools are intended to +run on the current system, and have not been built properly using +.Pa /src/sysroot . +.Ss Ports +You can place the source code for ports in +.Xr srctix 7 +format (has a +.Xr tixbuildinfo 7 +file) in the +.Pa /src/ports +directory and they will get built automatically when and installed into the +sysroot when building the whole operating system. Installable binary packages +are created in the +.Pa /src/repository/$HOST +directory using +.Xr tix-build 8 +directory and can be installed with +.Xr tix-install 8 . +If an existing binary package exists in the repository, it is used instead of +the building the port again. +.Pp +Ports are currently made using +.Xr cross-development 7 +as not all ports can be built natively yet. +.Pp +The ports system is described in detail in +.Xr porting-guide 7 . +.Ss Releases +CD-ROM release of the operating system can be built with the +.Sy iso +root makefile target. This will build the whole operating system, if not done +already, and produce a bootable iso for the current architecture in the +.Pa /src/builds +directory. The +.Sy sortix.iso +root makefile target will do the above and place a +.Pa sortix.iso +file in the current directory. +.Pp +The +.Sy release +root makefile target will run the +.Sy iso +target and prepare a +.Pa /src/release +directory with a directory structure and miscellaneous files suitable for a +formal online release. +.Sh SEE ALSO +.Xr make 1 , +.Xr cross-development 7 , +.Xr porting-guide 7 diff --git a/share/man/man7/hier.7 b/share/man/man7/hier.7 new file mode 100644 index 00000000..028464d1 --- /dev/null +++ b/share/man/man7/hier.7 @@ -0,0 +1,51 @@ +.Dd $Mdocdate: January 8 2016 $ +.Dt HIER 7 +.Os +.Sh NAME +.Nm hier +.Nd layout of filesystems +.Sh DESCRIPTION +The filesystem hierarchy is as follows: +.Bl -tag -width "12345678" +.It Pa / +Root directory. +.It Pa /bin +Programs. +.It Pa /boot +Boot programs, +.Xr kernel 7 , +.Xr initrd 7 , +bootloader. +.It Pa /dev +Devices. +.It Pa /etc +System-wide configuration. +.It Pa /home +User directories. +.It Pa /include +Development headers. +.It Pa /lib +Development libraries. +.It Pa /libexec +Non-user programs. +.It Pa /mnt +User mountpoints. +.It Pa /root +Directory of the root user. +.It Pa /sbin +System programs. +.It Pa /share +Architecture independent files. +.It Pa /src +System source code. +.It Pa /tix +Package management +.It Pa /tmp +Temporary files. +.It Pa /usr +Symlink to the current directory. +.It Pa /var +Various files. +.El +.Sh SEE ALSO +.Xr user-guide 7 diff --git a/share/man/man7/initrd.7 b/share/man/man7/initrd.7 new file mode 100644 index 00000000..d860d122 --- /dev/null +++ b/share/man/man7/initrd.7 @@ -0,0 +1,28 @@ +.Dd $Mdocdate: October 5 2015 $ +.Dt INITRD 7 +.Os +.Sh NAME +.Nm initrd +.Nd initialization ramdisk +.Sh SYNOPSIS +.Pa /boot/sortix.initrd +.Sh DESCRIPTION +.Pa /boot/sortix.initrd +is a achieve of a minimal userland loaded by the bootloader and passed to the +.Xr kernel 7 +that extracts it into the initial kernel memory root filesystem. The kernel +invokes the +.Xr init 8 +extracted from the initrd as +.Pa /bin/init . +.Pp +The initrd is in the custom format made by +.Xr mkinitrd 8 +and can be viewed with +.Xr initrdfs 8 . +.Sh SEE ALSO +.Xr initrd 7 , +.Xr kernel 7 , +.Xr init 8 , +.Xr initrdfs 8 , +.Xr mkinitrd 8 diff --git a/share/man/man7/kernel.7 b/share/man/man7/kernel.7 new file mode 100644 index 00000000..8ad674db --- /dev/null +++ b/share/man/man7/kernel.7 @@ -0,0 +1,40 @@ +.Dd $Mdocdate: October 5 2015 $ +.Dt KERNEL 7 +.Os +.Sh NAME +.Nm kernel +.Nd operating system kernel +.Sh SYNOPSIS +.Pa /boot/sortix.bin +.Op Fl \-init Ns "=" Ns Ar init-command-line +.Sh DESCRIPTION +.Pa /boot/sortix.bin +is the operating system +.Nm kernel . +It initializes and manages the hardware to provide a multitasking computing +environment. The kernel is a +.Xr multiboot 7 +compatible executable loaded by the bootloader along with a companion +.Xr initrd 7 +that contains a userland. +.Pp +The kernel extracts the initrd into the initial kernel memory root filesystem +and executes +.Xr init 8 +as +.Pa /bin/init . +The computer is powered off if this process exits 0, rebooted if it exits 1, +halted if it exits 2, and paniced otherwise. +.Pp +The options are as follows: +.Bl -tag -width "12345678" +.It Fl \-init Ns "=" Ns Ar init-command-line +The +.Ar init-command-line +argument is split into tokens and used as the command line to invoke the +specified +.Xr init 8 . +.El +.Sh SEE ALSO +.Xr initrd 7 , +.Xr init 8 diff --git a/share/man/man7/undocumented.7 b/share/man/man7/undocumented.7 new file mode 100644 index 00000000..72929e8d --- /dev/null +++ b/share/man/man7/undocumented.7 @@ -0,0 +1,10 @@ +.Dd $Mdocdate: December 28 2015 $ +.Dt UNDOCUMENTED 7 +.Os +.Sh NAME +.Nm undocumented +.Nd this manual page doesn't exist +.Sh DESCRIPTION +This manual page does not exist in Sortix at this time. +.Sh SEE ALSO +.Xr man 1 diff --git a/share/man/man7/user-guide.7 b/share/man/man7/user-guide.7 new file mode 100644 index 00000000..574ee71a --- /dev/null +++ b/share/man/man7/user-guide.7 @@ -0,0 +1,115 @@ +.Dd $Mdocdate: December 28 2015 $ +.Dt USER-GUIDE 7 +.Os +.Sh NAME +.Nm user-guide +.Nd basic system usage and overview +.Sh DESCRIPTION +Sortix is a small self-hosting Unix-like operating system developed since 2011. +This document covers matters relevant to new users from other Unix-like +operating systems. +.Ss Introduction +You will be presented a with standard Unix command line environment upon booting +the live environment. +.Ss Shutdown +.Xr init 8 +spawns a session after boot. This is a root shell if booted in +single-user mode. +.Pp +To power off from a single-user boot root shell, run +.Sy exit 0 +in the shell. To reboot, run +.Sy exit 1 +in the shell. +.Ss Keyboard Layout +The kernel has a default US keyboard layout compiled into it. +.Pp +You can change the current keyboard layout using +.Xr chkblayout 1 . +It loads the requested keyboard layout with the requested name from +.Pa /share/kblayout . +For instance to load a Danish keyboard layout: +.Pp +.Dl $ chkblayout dk +.Pp +The system has basic unicode capabilities but the kernel console font is limited +to characters in codepage 437. +.Ss Graphics +The bootloader prepares an appropriate video mode to the best of its abilities. +If you have a supported graphics card: +.Pp +.Bl -bullet -compact +.It +.Xr bga 4 - +Bochs Graphics Adapter found in virtual machines. +.El +.Pp +Then you can run +.Xr chvideomode 1 +to change the video mode after boot. +.Pp +.Dl $ chvideomode +.Ss Manual +The system manual can be viewed with the +.Xr man 1 +program. Sortix is currently in the process of being documented and many manual +pages are missing. The current priority is to document areas specific to Sortix +and assume standard knowledge from other operating system. +.Ss Editor +.Xr editor 1 +is the standard text file editor. +.Ss Games +The base system comes with games such as +.Xr asteroids 6 . +Additional third party games may be installed through ports. +.Ss Filesystem Hierarchy +The filesystem hierarchy is described in +.Xr hier 7 . +.Ss Memory Usage +The +.Xr memstat 1 +command shows the current memory usage. +.Ss Third Party Software +Releases come with useful third party software installed. The +.Pa /tix/installed.list +file lists all currently installed ports. +.Ss Source Code +Releases come full with the system source code in +.Pa /src +along with the tools to build it and develop it. The build +process is covered in +.Xr development 7 . +.Ss Mounting +You can mount ext2 partitions using +.Xr extfs 8 +and unmount them with +.Xr unmount 8 : +.Pp +.Dl $ extfs /dev/ahci0p1 /mnt +.Dl $ unmount /mnt +.Pp +Beware that +.Xr init 8 +is unaware of manual point points and powering off will not gracefully unmount. +The +.Xr extfs 8 +driver only supports the +.Sy large_file +and +.Sy filetype +ext2 extensions. You can make a compatible filesystem with: +.Pp +.Dl $ mkfs.ext2 -O none,large_file,filetype +.Ss Networking +Sortix does not have networking at this time. Unix sockets have a basic +implementation incapable of advanced features. The standard library and +kernel provides stubs for many network interfaces. +.Ss Development +The system is self-hosting and is capable of building itself as described in +.Xr development 7 . +Ports are cross-compiled as described in +.Xr cross-development 7 , +but it is becoming feasible to build a large number of them natively. +.Sh SEE ALSO +.Xr cross-development 7 , +.Xr development 7