2.1 Installing the Cross Compilers

The first thing to do is to install the RPM package that adds the Coyotos tool repository to your environment. To do this, you should (as root):

rpm -ivh http://www.eros-os.com/YUM/coyotos/fc8/Coyotos-Repository.fc8.noarch.rpm

If you are running Fedora Core 6 or Fedora 8, change the fc8 parts to fc6 or fc7 accordingly.

Once this package is installed, you will be able to install the Coyotos cross tools. We currently provide cross compilation kits for IA-32, Coldfire, and ARM/StrongArm targets [the ARM tools are not tested by us, but are actively used by the CapROS team. Depending on your target of interest, you should run one or more of:

yum install coyotos-i386-xenv
yum install coyotos-m68k-xenv
yum install coyotos-arm-xenv

That may take a while. Be patient. The advantage to installing this way is that you will automatically receive updates. Occasionally we have been known to make changes to the source tree that rely on an update in the cross tools. This is happening less and less often over time, but it still happens once in a while.

If we don't supply packaged tools for your platform, the altermative is to build them yourself. Instructions for this will be moving here shortly. For now, they can be found at the old site.

2.2 Check Out the Source Code

If you don't already have it, you will need to install mercurial. We use mercurial for our source code management. You can find information abuot how to use mercurial at http://selenic.com/mercurial/wiki. There is a pre-packaged version of mercurial in the Fedora repository for all recent versions of Fedora. While you are installing mercurial, you may also find the colordiff package useful.

[ui]
username=Danny Developer <danny@coderworks.org>
editor=vi

[extensions]
hgext.fetch=
hgext.gpg=

hg clone http://dev.eros-os.com/hg/coyotos/trunk coyotos

cd coyotos/src
hg clone http://dev.eros-os.com/hg/tutorial/trunk tutorial

cd coyotos/src
make

3.1 Re-Building the Tree From Scratch

We are currently (perhaps I should say constantly) working to improve the build process, especially in the documentation subtree. As with any operating system build tree, there are build order dependencies from one part of the tree to the next. Not all of these are capturable in the Makefiles. The big issue is that later subtrees depend on interfaces that are published by earlier subtrees.

Because of this, the first thing you should do if you suspect you have a build problem is to rebuild the tree from scratch. The simplest way to do this is:

cd coyotos/src
make pristine

This is a short-hand for the following commands:

cd coyotos/src
make distclean    # clean out the tree and everything that has been installed
make              # 2m37s elapsed with cold ccache, 2m16s with warm ccache

The Coyotos build is designed to use ccache if you have it installed. The ccache tool does amazing things to reduce build times, and we strongly recommend it. Ironically, this leaves the documentation tree as the "expensive" part of the build. If you are in a hurry, there are a couple of things that you can do to reduce build times.

• You can skip the build of the documentation tree entirely. Setting OPTIONAL_DIRS="" on your make command line will skip the build of the doc/ and tutorial/ subtrees.

  make OPTIONAL_DIRS=""  # 21s elapsed (warm ccache) # 45s
  elapsed (cold ccache)

• You can suppress generation of PDF files by restricting the targets for OSDoc. It is the PDF files that take all of the time:

  make OSDOC_TARGETS="%.html"  # 30s elapsed (warm ccache)

Please note that you should never change the value of OPTIONAL_DIRS when you are running make clean or make distclean. If you do so, those subdirectories will not be visited by the cleaning process. As a result, you will not get a clean build later.

3.2 Rebuilding A Particular Subtree

The convention in the Coyotos tree is that typing make package from within a package subtree rebuilds that subtree (from the top of the subtree) and installs its output. This build process assumes (without checking) that previous subtrees have been built. It also assumes that the results of previous builds of the current subtree will not alter the build result. This creates a requirement of convention: where the build of a given package requires interface specifications or mkimage component files that are provided by the same package, it should obtain these from the package source directory, not from the installed location. You can also type make world or make pristine, either of which will rebuild the entire tree proceeding from coyotos/src. If you simply type make, what happens depends on your current directory. If you are sitting in coyotos/src, typing make is equivalent to typing make world. If you are sitting within a package subtree, typing make is equivalent to typing make package.

At this point, we need to explain one piece of the makefile magic: how do the makefiles figure out where you are in the subtree? In principle, you could check out your tree anywhere. Two rules are applied in sequence:

1. If an environment variable COYOTOS_ROOT is set, it will be used. COYOTOS_ROOT tells the build system where the top of your tree is. It is not required that the top-level directory be named coyotos/, but it will avoid confusion if you follow this convention. The tree underneath the ${COYOTOS_ROOT} directory must follow the coyotos conventions.

2. If COYOTOS_ROOT is not set, the build system will examine your current working directory to see if it is of the form some/path/coyotos/src/ or some/path/coyotos/src/subdirectory. If so, it will assume that some/path/coyotos/src/ is the top of your development tree. As a practical matter, I don't think that any of the Coyotos or EROS developers (EROS makefiles used a similar trick) have bothered to set COYOTOS_ROOT in the last decade.

A minor word of caution: the mechanism used to find some/path/coyotos/src/ is not sophisticated. If you have a directory of the form path/coyotos/src/more/path/coyotos/src, please let us know what it does.

4.1 Interfaces, Objects, and Permissions