Aren/toaruos
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Move 'trying it out' to a separate doc file

Browse Source
This commit is contained in:
Kevin Lange 2013-11-29 19:13:14 -08:00
parent 6ee5fa2bc6
commit 694c9c2c21
2 changed files with 38 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
README.md
View File

@ -66,40 +66,9 @@ Additionally, a number of third-party software packages have been ported to と
For a historical look at とあるOS, please see [SCREENSHOTS.md](docs/SCREENSHOTS.md).
## Testing it Out ##
From some Linux hosts (Ubuntu/Debian, Fedora), you can clone the repository and run:
## Testing / Building / Installation ##
./build.sh
This will install the required dependencies, build the userspace libraries and toolchain, build the kernel, and give you a hard disk image.
You can then run `make run` or `make kvm` to run QEMU. An additional `make run-config` command is available that allows easy customization of the emulation environment through a config file (`.config`, see `util/config-parser` for available options).
While we only officially support QEMU, other environments - including actual hardware - should work given the appropriate tools. If you are eager to try とあるOS from a real machine, please use GRUB 2 and ensure that you provide the correct graphics payload options. You may find a sample GRUB configuration the `image-builder` directory.
### User Accounts ###
The default root password is `toor`. There is also a regular user `local` with password `local`. While general system security is lacking, most system-modifying calls to the kernel require root privileges.
### Cygwin ###
With some work, とあるOS is also known to build successfully under cygwin. Instructions are forthcoming.
### Making modifications
If you have made modifications to the kernel or userspace, `make` will suffice to build a new image and kernel. `build.sh` should only be used once when first cloning. If you have made modifications to the system call bindings for newlib, run `rebuild-newlib.sh` from the `toolchain` directory, then rebuild userspace applications as necessray.
### Prebuilt Images ###
Unfortunately, we are no longer able to host prebuilt images through GitHub. We are exploring other options for distributing pre-built images and are also working to provide an ISO distribution.
### Building an Image for VirtualBox, etc. ###
An experimental, unsupported image building tool that will produce a "production-ready" image, including GRUB 2, is provided in the `image-builder` directory. The script, `create-image.sh`, must be run as root and will produce a 1GB raw disk image which be converted to other formats as needed.
## Troubleshooting
If you have any issues at all while attempting to build とあるOS, or you would like help building on an unsupported platform, please join us on IRC (`#toaruos@irc.freenode.net`). Problems encountered while using the build scripts in an unsupported environment will not be considered bugs until thoroughly examined.
## Dependencies ##
A toolchain is provided and can be built through `build.sh`; this script should be able to install its own dependencies on Ubuntu/Debian and Fedora. Other environments are not supported, but examination for the script should provide a reference point on what packages are necessary.
The build process generally requires `yasm`, a working C compilation environment to build a cross toolchain of GCC and binutils, and `genext2fs` to generate EXT2 disk images from your host's userspace.
Please see [testing.md](docs/testing.md).
## References ##
Here are some tutorials we found useful early on:
@ -108,9 +77,9 @@ Here are some tutorials we found useful early on:
* [Bran's Kernel Development Tutorial](http://www.osdever.net/bkerndev/Docs/basickernel.htm)
* [Skelix's OS tutorial](http://skelix.net/skelixos/index_en.html)
# Licenses #
## Licenses ##
## ToAruOS Itself ##
### ToAruOS Itself ###
This project is released under the terms of the University of Illinois / NCSA Open Source License, an OSI- and FSF-approved, GPL-compatible open source license. The NCSA License is a derivative of the MIT license and the BSD license; it is reproduced here for your convenience:
@ -140,6 +109,6 @@ This project is released under the terms of the University of Illinois / NCSA Op
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
WITH THE SOFTWARE.
## Third-Party Packages ##
### Third-Party Packages ###
ToAruOS contains a number of third-party packages and software. As the number of third-party packages in the OS has increased drastically, I have moved the licenses to [THIRDPARTY.md](docs/THIRDPARTY.md).

33
docs/testing.md Normal file
View File

@ -0,0 +1,33 @@
# Testing とあるOS
Before trying とあるOS, keep in mind that it is a *hobby project*, not a professional operating system. Both the build process and the OS itself are prone problems and bugs. If you are not already familiar with systems software and emulators, using とあるOS may prove difficult and annoying. While I do my best to answer questions on IRC, I have a full-time job and other obligations that prevent me from being readily available and I do not put much effort into making the build system generally usable.
## Requirements ##
That said, there are a few things you will need before build とあるOS:
* **A capable build environment**: I develop under an Ubuntu derivative. I suggest the most recent *LTS* release of something like Xubuntu. The most recent version of Ubuntu ships with an a version of `automake` that removes a necessary legacy feature, but this can be corrected with a script provided in `toolchain/legacy-automake.sh`. If you are not using Ubuntu and you experience issues with missing packages, I can attempt to help, but provide no warranty of support.
* **An understanding of Unix build tools**: The build system for とあるOS is a disparate combination of shell scripts, Makefiles, and a bit of Python magic. If you are not already familiar with normal build tools on Unix-like systems, no amount of automation will help you resolve issues.
On Ubuntu and Debian systems, the automated build scripts will attempt to install the prerequisite packages for building the toolchain. The toolchain is then used to build a number of libraries for userspace, the userspace itself, and then the kernel. The standard build tools do not create a bootable harddisk image, though a tool is provided to do this if you want to test with an emulator other than qemu.
## Building ##
Once you have a capable build environment set up and the repository cloned, start by running `./build.sh`. This will either prompt you for your password (using `sudo` to attempt to install a number of development packages) or yell about not knowing what you're on. In the latter case, the script includes a list of packages with both Debian names and Fedora names, and you should attempt to install of them using your distribution's package manager.
A complete build with `build.sh` takes about 30 minutes on my hardware, but I have a rather fast Internet connection and a very capable CPU - it could take many hours on less capable hardware.
If the build process fails, your best bet for support is sit on my IRC channel (`#toaruos` on Freenode), post your question, and *wait* for me to eventually answer it (if I can). Leaving after five minutes will not get your question answered. If you are not around when I see your question, I won't even attempt to answer it. Do not attempt to report issues with build scripts as bugs - while some issues may actually be bugs in the scripts, they are usually not.
When the first build has completed, you can use `make` instead of `build.sh` for future builds. This will skip rebuilding the entire toolchain. If you're serious about developing, you may need to run `build.sh` in some cases (such as after making changes to the Newlib glue layer), but for most cases it is a waste of time.
The Makefile also includes some convenience targets for running とあるOS in QEMU. The most important of these is `make kvm`, which will attempt to run a fairly standard graphical environment, with KVM acceleration enabled. If you don't have KVM available, you may use `make run`, but expect the GUI to run poorly as it relies rather heavily on the CPU for compositing.
The default image provides two user accounts, `root` with password `toor` and `local` with password `local`. The latter is the preferred account: as in any Unix-like system, you should not normally log in as `root`. Some system calls require root-level permissions, but as of writing this documentation filesystem permissions are not implemented.
### Building an Image for VirtualBox, etc. ###
An experimental, unsupported image building tool that will produce a "production-ready" image, including GRUB 2, is provided in the `image-builder` directory. The script, `create-image.sh`, must be run as root and will produce a 1GB raw disk image which be converted to other formats as needed.
## Troubleshooting
If you have any issues at all while attempting to build とあるOS, or you would like help building on an unsupported platform, please join us on IRC (`#toaruos@irc.freenode.net`). Problems encountered while using the build scripts in an unsupported environment will not be considered bugs until thoroughly examined.