1.1 Recognized Targets

The targets that are currently recognized take the form ``os-architecture'' where ``os'' is one of ``coyotos'' or ``capros'',¹ and ``architecture'' is one of:

We would eventually like to see support for x86_64, but no port of newlib has been done to that platform yet.

1.2 Setting up on Coyotos

The best development environment for Coyotos is, of course, Coyotos itself. If you cannot find a Coyotos port for your platform, please write one.

Okay, okay. This isn't likely for a while, so let's move on to those other systems that you may need to suffer with until an upgrade to Coyotos becomes available...

1.3 Setting up on Linux/YUM Systems

To make getting going on Linux easy, we have built a package to update your yum configuration. Once this is installed the rest is easy. To install this package:

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 the repository is set up, you can install some helpful tools (and a required library) by running (as root):

yum install coyotos-i386-xenv

or possibly coyotos-arm-xenv or coyotos-m68k-xenv. This will get you all of the tools in the Coyotos cross environment for your target.

If you are asked whether to import the signing key, you will need to say "yes". This key is used to sign all of our packages. If you wish to ensure that the key is authentic, you can check the key fingerprint at pgp.mit.edu key server by searching for packager@eros-os.org if you choose to do so. If imported, you should find that it is signed using my (Jonathan Shapiro's) offline signing key. The fingerprint of my offline signing key is DFAB6639. If you export this key, you can directly import the ascii armored file using rpm --import.

The coyotos-i386-xenv package is a ``virtual'' package — it simply supplies the necessary dependencies so that YUM will find all of the pieces you need. As of this writing, the packages installed are:

If you are targeting the Pentium family, you may also find it helpful to install qemu, a full-machine emulator for the PC. We rely on this heavily for debugging, and if you don't have a lab full of machines it is probably the best way to experiment. You can install this by:

yum install qemu

The qemu package is a native tool, so it installs in the customary directories.

All of the Coyotos cross environment tools install into /coyotos/. If you install them with YUM, you can remove them by:

rpm -e `rpm -q -a |grep coyotos`
rpm -e qemu libsherpa libsherpa-devel

If you are on a RPM system but you prefer not to use the YUM-based method, you are certainly welcome to install these packages by hand, but it will be harder to stay up to date. Alternatively, you can build the cross environment yourself (see below).

We would be willing to set up the necessary metadata for users of apt as well, but we would need some guidance. A further concern is that we don't tend to run and Debian systems, so it would be difficult to test the RPMs for that environment.

1.4 Setting up on Other UNIX's

It's really a much better plan to use the provided cross environment packages, because that way we can easily provide updates to the cross tools that will arrive in the normal way for your system. If you are building on some other UNIX derivative that has not accepted the Dao of YUM, you may find that nothing will do but to build the cross environment for yourself. If that is the case, you can fetch it from the repository using mercurial.

First, as root, you should create the directory /coyotos and use the chown command to make it writable to you and owned by you:

# as root:
mkdir /coyotos
chown yourlogin:yourgroup /coytos

hg clone http://dev.eros-os.com/hg/ccs-xenv/trunk ccs-xenv
(cd ccs-xenv; make -f Makefile.xenv TARGETS="coyotos-i386")

(cd ccs-xenv; make -f Makefile.xenv TARGETS="coyotos-m68k coyotos-i386")

(cd ccs-xenv; make -f Makefile.xenv TARGETS="coyotos-i386" CROSSROOT=$HOME/coyotos-xenv)

1.5 Setting up on Windows

You can download a set of Fedora installation CD's from our Fedora mirror repository. When you get to the place where it asks whether you want to delete all existing partitions, remember that as much as you may want to, you probably can't afford to lose your Windows install quite yet.

3.1 Impact of IDL

Coyotos is an IDL-based system. The interfaces for Coyotos subsystems are specified using an interface description language (IDL). Interface description filenames end with .capidl for ``capability IDL.'' The IDL files are used to generate:

• Client-side header files needed by a client when calling a provider.

• Client-side stub libraries that translate provider invocation arguments into a Coyotos interprocess communication (IPC) message.

• XML documentation that describes the interface. This documentation is later gathered to create the system object reference manual.

• Server-side header files needed by a provider to implement an CapIDL interface.

• Server-side stub code that demarshals requests and marshals responses. This is also used to implement a CapIDL interface.

It is possible to have circular dependencies among interfaces, but not among interface implementations.

In general, the client-side IDL headers need to be generated before a given piece of client code can be compiled, and the client-side stubs need to be generated before client code can be linked. There are two ways in which this might be implemented:

1. Each client application can generate and compile it's own copy of the necessary client headers and client stub libraries. This is feasible, but it is a nuisance and it makes the compile process take an unreasonably long time.

2. A pre-pass can be made to generate the headers and client stubs, which can then be used in common by all of the clients that depend on them. This has the advantage of not building the headers and stubs redundantly, but has the cost that the unit of build is now the package rather than the directory.

We initially tried the first approach in the EROS build process. We found that it was excessively inconvenient, and we switched to the second method. The Coyotos build process uses the second method. In the EROS build system, we found that the automatic dependency generation mechanism does a pretty good job of avoiding unnecessary rebuilds.

However, this approach creates a quandry for foreign packages, because we aren't in a position to modify the makefiles of those packages to force a complete package rebuild whenever make is invoked. Even if we could resolve this, the foreign packages aren't necessarily designed to be friendly to the complete package build discipline. Therefore:

3.2 Normal Build Sequence

When the make command is invoked from the coyotos/src directory, each package root directory is visited in order, and the make install command is issued for that package. The build order is:

1. The coyotos/src/ccs package if present,³

2. The coyotos/src/sys package,

3. Packages in coyotos/src/lib, in the order specified in the top-level library makefile,

4. Packages in coyotos/src/bin in the order specified in the top-level binaries makefile,

5. Packages in coyotos/src/examples in the order specified in the top-level binaries makefile,

Because packages can be foreign, the internal build rules for a given package are inherently package dependent. All package-level makefiles are expected to implement the following make targets:

• make install Build and install all content in subdirectories of this one, then build and install the content of the current directory.

• make world Rebuild the entire source tree from the top.

• make package Rebuild the current package by issuing make install from the top of the package tree. In Coyotos packages, this is usually the default make target.

• make clean Delete all generated content in the current directory and its subdirectories.

• make nodepend Discard all automatically generated dependency information from the tree. Dependency information is usually updated automatically by the Coyotos makefile rules, but it sometimes becomes out of date and must be forcibly deleted. When doing this, it is often necessary to use make -k, and it is recommended that a clean should be performed as well:

  make -k clean nodepend
  

Each of the make targets above is also available at the coyotos/src level of the tree, but the scope of effect is the entire source tree rather than a single package. In addition, the following targets are available at the top level:

• make targdir-clobber Delete the entire installed directory tree.

• make pristine Wipes out the installed directory tree, performs a clean on every package, removes all automatically generated dependencies, and then rebuilds the entire tree from scratch.

At the top level of the source tree, the default make target is make world.

5.1 XML Documentation

The Coyotos documentation system is based on the assumption that Coyotos documentation is written in XML using the osdoc DTD. The Coyotos documentation tree includes a set of XSLT transformers that produce both online (HTML) and offline (PDF) versions of these documents. The PDF versions are generated using LaTeX.

The document generation process is controlled by the XMLSOURCE variable. This variable should be defined before including makerules.mk. It's content should be a list of XML input file names without the .xml file name suffix. For the document you are reading, the relevant line of the makefile is:

XMLSOURCE=build

The documentation support makefile fragments are only included if the XMLSOURCE variable is defined. By default, both HTML and PDF output are generated for all XML input documents.

The XML translation mechanism also knows how to generate .eps and .gif (soon switching to PNG) files from XFIG input. Figure files should be identified by the FIGSOURCE makefile variable. As with XMLSOURCE, this should be defined before makerules.mk is included:

FIGSOURCE=fig1.fig fig2.fig fig3.fig

We need better figure management system than XFIG, but the current system is better than nothing.

Because generating .gif and .eps files from the .fig sources is so fast, and because the output all goes in the same directory in any case, the current xml makefile fragments don't really attempt to associate individual figures to individual documents within a single XML document directory.

5.2 Building Object Code

In contrast to documentation, which is driven from the list of source files, object code compilation is driven from the list of target files. An example is provided below.

Several of the makefile variables shown deserve particular attention, because they control various aspects of the build process:

And here is an annotated example:

default: package

COYOTOS_SRC=../../..
# Use the CROSS_BUILD variable to say that this is a cross build.
# If absent, the build is assumed to be a host build.
CROSS_BUILD=yes  

# Convention: binaries (or libraries) built in the current 
# directory are named by the TARGETS variable.
TARGETS=$(BUILDDIR)/sample

# Convention: bootstrap image map files must be named by the
# IMGMAP variable. If x.imgmap is listed in the IMGMAP
# variable, then $(BUILDDIR)/x-constituents.h will be automatically generated
# by the automatic make rules.
IMGMAP=sample.imgmap

# Convention: all object files produced in this directory should
# be listed in the OBJECTS variable, and should
# be prefixed by "$(BUILDDIR)/". If there are multiple targets, each
# should have its own specialized X_OBJECTS, Y_OBJECTS variables,
# which should be accumulated into OBJECTS
OBJECTS=$(BUILDDIR)/sample.o

# Default optimization level can be overridden by setting the value
# of OPTIM.
OPTIM=-O
# Include path can be modified by altering value of INC
INC=-I$(EROS_ROOT)/include
# Additional defines can be provided by altering value of DEFS
DEFS=-DSOMEDEF

include $(COYOTOS_SRC)/build/make/makerules.mk

# Convention: local 'all' target causes $(TARGETS) to be built.
# That is, 'all' is the local build target. The 'all' target
# should not recurse — it is assumed that the install
# target has already done that.
all: $(TARGETS)

# Link rule for the sample binary (this will need to change for
# Coyotos)
$(BUILDDIR)/sample: $(OBJECTS) $(DOMCRT0) $(DOMLIB)
	$(DOMLINK) $(DOMLINKOPT) $(DOMCRT0) $(OBJECTS) -lsmall $(DOMLIB) -o $@

# Convention: 'install' target depends on 'all', installs
# targets into destination directory relative to COYOTOS_ROOT
install: all
	$(INSTALL) -d $(COYOTOS_ROOT)/domain
	$(INSTALL) -m 755 $(TARGETS) $(COYOTOS_ROOT)/domain
	$(INSTALL) -m 644 $(IMGMAP) $(COYOTOS_ROOT)/domain

# Convention: last line of makefile should be the following, which
# ensures that existing automatic dependency files are reloaded
# after each execution.
-include $(BUILDDIR)/.*.m

Normally, the above mechanisms are sufficient. The makerules.mk file includes makevars.mk, which internally constructs values for the usual make variables GCCFLAGS, GPLUSFLAGS, and so forth. Along the way, the value of CROSS_BUILD is used to decide how to set the values of variables GCC, GPLUS, LD, and friends. A more complete list of all variables associated with the build mechanism is certainly needed. For a better sense of what is going on, see makevars.mk and build-rules.mk. The variable names definitely need to be regularized and cleaned up.

The compilation mechanism is tuned to rebuild the associated automatic dependency files whenever an object file is rebuilt.