Distribution Contents

The OpenBinder distribution is divided into a number of top-level directories for the different kinds of items that are included. This page is organized in the same way, providing a brief description of each of the items that are included.

build

This directory is not included in the distribution, but will created for you when you build OpenBinder. It contains all of the build outputs (except for the kernel module), and is thus safe to completely remove in which case the needed contents will be recreated at the next build. The build results are placed into a number of subdirectories here:

bin: Executable Linux commands, from the commands, servers, and tools source directories.
docs: Output from doxygen (make docs).
headers: C++ headers generated by pidgen from the source IDL files in interfaces.
lib: Linux libraries (shared and static) from the source libraries directory.
obj: All intermediate build files.
packages: Final Binder package directories, created from the source components and samples directories.
scripts: Script files, both Linux shell (ending with .sh) and Binder shell (ending with .bsh), from the source scripts directory.

build_system

The OpenBinder make-based build system is here. This directory includes both a basic file (definitions.make) as well as various template files used to generate rules to create various types of output.

The subdirectory doxygen here contains files for generating the Doxygen documentation. Of particular note here is the front page of the documentation, in mainpage.h.

commands

Linux command-line tools related to working with the Binder.

3way: A test app that creates three processes and sends Binder transactions between them.
bomber: A test app that forks and kills a large number of processes that hold object references between them.
bsh: A command that starts a Binder shell session. The smooved service must already be running.

components

This directory contains the implementation for various Binder components and Makefiles for compiling them into packages. It is organized in a series of sub-directories for different kinds of components.

kits

These are various components related to specific Binder kits. The only one currently included is CatalogMirror, a component wrapper for the BCatalogMirror class.

services

These are Binder components that are intended to be used as services i.e., published in the services directory.

base: A common package for basic services. Currently only includes the Informant service.
MemoryDealer: The service provides a common shared memory area that others can perform allocations in. It is a useful demonstration of the IMemory and IMemoryHeap APIs, although this implementation should be moved into libbinder so that others can easily create their own shared memory areas.
Settings: The Settings Catalog, which maintains a hierarchical data organization that is stored in a persistent XML file.
TokenSource: An example class for generating Binder object tokens that can be used to track state in a robust way (recovering from process crashes).

tools

These components are command line tools.

BinderShell: This is the implementation of the BinderShell. It also includes a large number of components providing all of the basic shell commands.
commands/atom: A shell command for working with the SAtom Debugging facility.
commands/bperf: A command for running a wide variety of Binder performance and validation tests.

docs

This directory contains top-level documentation on OpenBinder. The detailed documentation on the Binder itself is stored along with its implementation, in libraries/libbinder/docs.

headers

These are the shared header files for the OpenBinder APIs. They are organized into "kits", a collection of related APIs. One or more kits are bundled together into a library. Currently all kits are compiled into the libbinder.so library.

app: The Application Kit, primarily the basic Binder Shell command interface and implementation (ICommand, BCommand, SGetOpts).
dmprovider: Headers for an example (not buildable) implementation of the Binder Data Model APIs on the SQL-like APIs that were in the Cobalt Data Manager.
package: The Package Kit, containing the implementation of the Package Manager.
package_p: The private parts of the Package Kit. All of the current Package Kit is here, which smooved uses to start the package service.
services: The Services Kit for generic system service. Currently includes the implementation of the Informant service.
storage: The Storage Kit, for working with data and storage. Primarily composed of classes for implementing the Binder Data Model interfaces.
support: The Support Kit, core Binder APIs. Currently contains the headers for both the Support Kit and Binder Kit APIs that this documentation describes.
support_p: Private headers for the Support Kit.
xml: The XML Kit, the Binder's XML parser. This should be replaced by a standard XML parse.
xml_p: Private parts of the XML Kit.

interfaces

These are IDL files describing public Binder interfaces. They are organized into kits exactly the same way as the headers, and the generated headers get built with the same structure into the build directory.

app: Application Kit interfaces.
package: Package Kit interfaces.
service: Service Kit interfaces
support: Support Kit interfaces.

libraries

Code for the OpenBinder libraries, both shared and static.

libbinder: This is the full Binder implementation, collecting together the Support, Binder, Storage, Services, and App Kits. There are actually two libraries that are generated from this code: libbinder.so is the normal shared library that clients link against, and libbinder_bootstrap.a is a small subset static library that is used to build tools such as pidgen (which must be built before the full libbinder.so, with its interfaces, can be created).
libbinder_component_glue: Glue code that components must link against. This provides the per-package implementation needed for SPackageSptr and other package manager facilities to work.
libbinder_glue: Glue code that libraries and executables (but not components) linking against libbinder must also include.
libdmprovider: An example of how to implement the Binder Data Model APIs on the SQL-like data store. While this requires the Cobalt Data Manager so is not useful as-is, it can be used as a reference for how one might go about such an implementation.

modules

This directory contains the Binder kernel module, for performing IPC between processes. It is an optional part of the system; if not built, all of the other Binder features except for multi-process support will still work.

samples

Sample code.

SampleComponent: The basic sample code for writing a component, implementing a Binder Shell command.
SampleService: An example of writing a service. Includes both a component implementing a service, and a shared library showing how you can provide plain C APIs for working with the service.
SampleProcess: An example of a service that automatically runs in its own process.
ShellService: The SampleService example component, implemented with a Binder Shell script!

scripts

These are various shell scripts, both for a normal Linux shell (using a .sh suffix) and the Binder shell (using a .bsh suffix).

Note:: You should not use these directly, but rather the corresponding outputs generated by the build system in build/scripts.

boot_script.bsh: A Binder shell boot script that smooved can run to set up various standard services.
process_wrapper_gdb.cmds, process_wrapper_gdb.sh, process_wrapper.sh: These files can be used with the BINDER_PROCESS_WRAPPER feature to wrap every new Binder process with its own xterm and gdb session.
setup_env.sh: A Linux shell script that will set up your environment variables (PATH, LD_LIBRARY_PATH, BINDER_PACKAGE_PATH) so that you can run smooved and bsh directly from the command line.
test.bsh: A Binder shell command that runs some standard bperf tests.
user_context.bsh: Script that is run by boot_script.bsh to set up the user context.

servers

These are standard Linux commands that are basic parts of the Binder runtime.

binderproc

This is the executable that the Binder runs when it is created a new process. It sets up the Binder environment and connection correctly so that the parent can get its IProcess to instantiate components inside of it.

smooved

The smooved executable is the main Binder server, and must be running for other Binder services to be available.

The smooved application itself does very little. Its main purpose is to:

Create the root Binder context, basically by instantiating a BCatalog object.
If the Binder kernel module is available, become the global host of the root namespace.
Create and start the Package Manager, by instantiating the standard package manager class and adding it to the root context under /packages.
Create a simple process manager and publish it in the root context under /processes. Note: This should be changed to a component that is created and published by the boot script.
Say Bring It On, and run either a boot script such as scripts/boot_script.sh and/or start an interactive Binder shell session, depending on the arguments supplied on the command line.

Though smooved itself does not do a whole lot, there is often a significant amount of code running in its process since that is the initial default location in which components are instantiated. For example, the standard boot script creates all of the standard services and BCatalogMirror objects for the user context in the smooved process.

For more custom configurations, you can easily implement a replacement for smooved that only does as little or as much as you need. Note that, however, when multiprocess support is being used (that is, when the Binder kernel module is available), there can be only one process that is the host of the root SContext namespace. This is the process from which the SContext::UserContext() and SContext::SystemContext() methods retrieve their context object.

That said, there shouldn't be a reason why an application couldn't create its own root context and Package Manager, and simply ignore whatever multiprocess capability might be around by not trying to become the host of the root namespace. Provided that its components aren't using SContext::UserContext() or SContext::SystemContext(), that application could even still make use of the normal multiprocess APIs such as creating new processes with SContext::NewProcess() and instantiating components there.

tools

Linux command line tools that are used by the build system to generate other parts of the final system. When building OpenBinder for the first time, these tools will be created as they are needed to build other parts of the package.

makestrings

This command line tool generates string resources for inclusion in a package.

pidgen

The Binder IDL compiler. Takes IDL files as input, and generates C++ headers and implementations as output. See pidgen for more information.

Note that in the OpenBinder build system, as long as the pidgen tool is already available, it will not be considered as a prerequisite for generating sources from the IDL files. That is, if you modify the pidgen tool, this will not automatically cause it to be re-run on the IDL files. To force it to be run, you can use the pidgen goal, such as "make user pidgen".