Syllable
Syllable Documentation
Frequently Asked Questions

1. About Syllable
 1.1 What languages is Syllable written in?
 1.2 What license is Syllable released under?
 1.3 How can I get the source code for Syllable?

2. Development environment
 2.1 What development tools are available for Syllable?
 2.2 What editors can I use?

3. Builder
 3.1 What is Builder?
 3.2 Can I write my own Builder recipes?
 3.3 I tried to build some software and it failed. Why?

4. Application development
 4.1 Where can I find API documentation?
 4.2 How POSIX compliant is Syllable?
 4.3 What thread model does Syllable use?
 4.4 What thread API's does Syllable offer?
 4.5 Can I use my favourite language on Syllable?
 4.6 What are file attributes?
 4.7 How are configuration settings managed?

5. Kernel and driver development
 5.1 Can you give me a basic overview of the kernel?
 5.2 Can I just recompile Linux drivers for Syllable?
 5.3 Do I have to worry about concurrency?

1. About Syllable

The kernel, drivers and low level system libraries are all written in C and some assembly. The high level system libraries and servers are written in C++. Applications are written in C++ and some system tools are written in C.

Syllable has also started to integrate the ORCA language. ORCA is an Open Source implementation of the REBOL language. A handful of system tools are currently written in ORCA, and more will be added as ORCA matures and the integration is expanded.

There are also a few Ruby applications, mainly the installer and Builder. This will eventually be replaced with new versions written in ORCA. Using Ruby on Syllable is discouraged in favour of ORCA.

The kernel, the majority of the drivers and most of the applications that are distributed with Syllable are released under the GNU General Public License (GPL). The system libraries are released under the GNU Lesser Public License (LGPL), which allows them to be used by software which is released under other licenses.

Some libraries and drivers may be licensed under different licenses including the BSD "3 clause" license, the ZLib license, MIT, X and even BeOS Sample Source license.

Third party software for Syllable may be licensed under any terms the author chooses.

All of the source code for Syllable is available from our CVS repository hosted at SourceForge. Read-only anonymous CVS access is possible. The repository URL is

pserver:anonymous@syllable.cvs.sourceforge.net:/cvsroot/syllable

Most of the current code for Syllable is under syllable/system/

You can browse the entire CVS repository via http://syllable.cvs.sourceforge.net/syllable/syllable/system/

A Zip containing a copy of the source used to build a release can be downloaded from SourceForge at http://sourceforge.net/project/showfiles.php?group_id=55553&package_id=50546

2. Development environment

Syllable uses the familiar GNU tool chain. This includes GCC, GNU Binutils, GNU Make, the AutoTools (AutoConf, AutoMake and LibTool) and various other smaller utilities that most open source or Unix developers will already be familiar with.

There is also an Integrated Development Environment (IDE) for Syllable, sIDE. sIDE includes a GUI designer, projects and a developers editor.

Syllable has some native and non-native editors available. Native editors include Sourcery (part of sIDE) and AEdit (a basic text editor). Non-native, command-line editors include VIm, JOE and Nano. An old port of XEMacs 19 used to be available but no longer works on Syllable. It may be possible to build a command line version of EMacs or XEMacs, but no one seems to have done it yet.

3. Builder

Builder is a powerful application for Syllable developers that can be used to build both third party applications and Syllable itself, from source code. To do this, Builder uses "recipes" which tell it what steps are required to patch, configure, build and install the software on Syllable.

Yes. Writing a recipe for a new package is very easy. You can reference the existing Builder recipes, and there is a "template" recipe, skeleton.recipe, that documents all of the available recipe directives. There is also a README document that explains how to use Builder.

More documentation on Builder will become available in the future.

First of all, check the "status" directive in the recipe you are trying to build. If it is "broken" then the software is known to not build correctly. If you think you can help to fix the software to work correctly, we always welcome any patches.

If the status is not "broken" then you should ensure you have installed all of the tools and dependencies required by the package you are building. The "needs" and "build-needs" directives usually lists the dependencies.

4. Application development

http://web.syllable.org/documentation/index.html contains links to the DoxyGen documentation for the high level application APIs (LibSyllable), media APIs and some of the kernel APIs.

We aim to make Syllable as POSIX and Single Unix Specification (SuS) compliant as possible, as long as it does not interfere with the high level design of Syllable. In practice this means that Syllable is compliant enough that a large amount of existing Unix and Linux software can compile on Syllable very easily, in most cases without any changes.

POSIX/SuS compliance is improving as we continue to develop Syllable and fix bugs. If you find and API or function which is not implemented or which you think is not compliant with the standard, please let us know or provide us with a patch that fixes the issue.

Threads are fully managed by the kernel and there is a 1:1 mapping to user threads. Every process has at least one thread. The kernel and device drivers can also easily create their own threads. Threads are directly scheduled by the kernel (some other OSes call these "Kernel Schedulable Entities" or "KSEs").

There is a native thread API which is available to both user and kernel threads. This is spawn_thread() and related functions.

There is also the os::Thread C++ class available in LibSyllable which provides a very simple C++ thread API on top of the native thread API.

Syllable also offers a nearly complete implementation of POSIX threads (PThreads). PThreads support is provided for compatibility with cross-platform software and should not be used for native Syllable applications.

Finally the GThread class offered by GLib is also implemented in Syllable. GThread is implemented on top of PThreads and is provided for compatibility reasons only. We urge you not to use GThread at all. If you require a portable thread API, please use PThreads.

That depends. A lot of scripting languages are supported on Syllable, but there are no bindings to any of the native Syllable APIs. Currently the only languages fully supported on Syllable are C and C++, and ORCA/REBOL support will improve over time. Other languages such as Java, C# and Pascal could all theoretically work on Syllable but no one has yet completely ported them.

File attributes are streams of data that can be associated to entries (directories, files, symbolic links) in the file system. Each attribute is associated with a name that must be unique within the file/dir/symlink it is added to. An attribute can hold as much or as little data as you want (they have the same size limits as regular files) and it can contain typed data (integer/float/string/etc.) or just a raw stream of bytes (such as an icon image).

Attributes are implemented in the native Syllable file system but are not entirely used in it yet. It will however be a very important part of the desktop manager where it will be used to keep file/directory specific icons, icon-positions, file-types (the mime-type of a file) etc. The desktop manager will use the icon information to visually present the file or directory and it will use the type information to decide what application to launch if a data file of some kind are double-clicked (it will have a data-base with information about what applications handle which mime-types so if you click on a "image/jpeg" type file it will launch a bitmap-viewer, if you click on a file with type "text/plain" it will launch a notepad like text editor, and a "text/x-sourcecode" would launch a more advanced source-code editor etc. It will also be possible to tell the desktop manager to launch a specific application for any given file or directory independent of it's mime type by adding an attribute that points to a specific application. It will also be possible to give additional arguments to the launched application by adding them as an attribute of the data file. The concept of attributes comes from BeOS that again have the concept from MacOS. The attributes in BeOS and Syllable have a great advantage over the MacOS "resource fork" in that there can be an unlimited number of them for each file (each identified by a name) and there is no size limit on each attribute.

Native Syllable applications should use the os::Settings class, which is provided by LibSyllable. This takes an os::Message class, flattens it and streams it to disk. The advantage is that this is very flexible and very simple to use. The disadvantage is the configuration files are binary files and therefore not human-readable.

5. Kernel and driver development

The kernel is a modular, monolithic design. On the surface, many of the sub-systems within the kernel are similar to Linux in many ways, but a lot of functionality is placed in modules. This includes the network interface drivers (e.g. eth_if, ppp_if), the bus managers (PCI, USB etc.), the device drivers and the file system drivers.

Most of the kernel is fairly conservative and should be familiar to anyone who has some knowledge of Linux, BSD or Minix. One major difference is that parts of the kernel are multi-threaded and all syscalls are fully re-entrant.

Unlike many other UNIX-like OSes, the Run Time Linker Daemon (RTLD) and ELF loader are all part of the kernel. There is no ld.so user-space RTLD. This allows us to build all of the kernel modules and device drivers as ELF Dynamic Shared Objects (DSOs, otherwise known as shared libraries).

The syscall and driver APIs are well defined and there is an established API between drivers and the kernel. This means that Syllable is able to maintain a stable driver ABI. Most device drivers are capable of being both forward and backward compatible, even with the kernel under development.

Not quite. Although parts of the driver API are similar between Linux and Syllable, they are far from identical. However it is quite simple to port most drivers from Linux to Syllable, and with a few changes most drivers will work just as well on Syllable.

A system header, linux_compat.h, is provided which includes some macros, types and functions which help to make Syllable look as much like Linux as possible. This is largely used by many of the network card drivers, where the differences between Linux and Syllable are smallest. It can be used with other drivers, but developers are encouraged to port or write drivers for Syllable without using linux_compat.h if possible.

Yes. Syllable is both threaded and capable of running on multiple processors, so concurrency issues are very real. Unlike Linux, Syllable only provides one kernel which can run on both SMP and non-SMP machines. Any code or drivers for Syllable must be written for the possibility of running on a machine with more than one CPU, even if you are not making use of threads.

The good news is that the kernel takes care of most concurrency issues for you: kernel API functions deal with locking internally, so there is no need for the caller to do anything before or after calling a kernel function.

Syllable is also intended for use on IA-32 (and in the future, AMD64) platforms, so there are very few read/write ordering issues to deal with. The macro smp_wmb() is provided to force an ordered write to memory. No other memory barriers are required.

If you're unsure about concurrency issues with any code you are writing, the Syllable developers can provide further advice and guidance.