Improve this page Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using local clone. Page wiki View or edit the community-maintained wiki page associated with this page.

Deimos

Deimos is a collection of repositories for interfacing C libraries. Its aim is to integrate already available C libraries. Since D is binary compatible with C ABI code a plentiful of libraries is potentially available in D. Deimos repositories are available at github.

How to use a Deimos repository

Each Deimos repository is named after the corresponding C library. Each must follow the directory structure

C/          // contains the original C header files
deimos/     // contains the translated D modules
examples/   // contains examples
README      //

Each library should contain a README in the root folder. The README file should contain exact source and version of the C library. Furthermore it should contain specific notes about the usage of the D import file.

Every library should contain a simple D example. This could be used for basic self testing.

To use a Deimos library you need to clone/submodule its repository. Adjust the import path and link/load the C library. E.g. to use OpenSSL execute

git clone git://github.com/D-Programming-Deimos/openssl.git
dmd -Iopenssl/ -lopenssl ...

How to create a Deimos repository

Deimos is constantly growing but having more libraries at your finger tips is always an improvement. Let's walk through the basic steps of creating a Deimos repository.

Initialize the repository

git init
touch README.md
git add README.md
git commit

Add the plain C header files in branch C

git checkout -b C
mkdir C/
cp -a path/to/include/files/* C/
git add C/
git commit

Merge branch C and copy C header files to deimos/

git checkout master
git merge C
cp -a C/ deimos/
git commit

For each file a proper module declaration has to be provided. That is, you have to specify a fully qualified module name (see Module). The fully qualified module name has to start with deimos.. In addition

each slash (/) has to be replaced by a dot (.)
each dash (-) has to be replaced by a dot (.)
each D keyword gets a underscore (_) appended

llvm-c/Analysis.h

deimos.llvm.c.Analysis

foo/bar/if.h

deimos.foo.bar.if_.

Once the D module name is fixed the C header file should be moved using git mv where the new file name follows the chosen module name (see Module). E.g. the module llvm.c.Analysis is in the package c, which itself is a package of llvm which means llvm-c/Analysis.h will be moved to deimos/llvm/c/Analysis.d. Note, that if the module name contains dots (i.e. the module is part of a package) a hierarchy of directories has to be created.

Once all header files are moved make a commit. This commit only reflects the renaming and allows git to track the renaming of each file. Never rename a file and change its content as this will destroy git's ability to track a moved file.

Changing the contents of each module

So far, each C header file was renamed to a D module. Next the contents of each module will be adjusted. In general following the advices from interfacing to c is recommended.

The D files should try to do as least modifications as possible to simplify updates of the C headers. This includes leaving comments intact. The copyright for the D files should match the one being used by the C header as they are derived work.

In particular,

Replace C's include

Each #include needs to have a corresponding import path.to.header;

Add extern(C) and nothrow

// imports

extern(C) nothrow:

// contents

Replacing types

Types are replaced according to interfacing to c (see table "Data Type Compatibility"). Further, const T* must be replaced by const(T)*.

Versioning

Version tags should match the ones being used by the C headers.

Replacing macros

Translated header should not require linkage of any D binary. Necessary D functions can be written as nullary templates.

#define GET(x) x.value

int GET()(X x) { return x.value; }

Tag with library version

We strongly recommend to follow these guidelines to warrant inclusion in Deimos. However, deviation may be necessary in some cases.

To push the repository upstream a repository has to be created at github. Ask for such in digitalmars.D. Finally, create a pull request.

How to update an existing Deimos repository

Checkout the branch C

git checkout C
copy the header files

Merge the branch C and fix conflicts.

git checkout master
git merge C
// fix conflicts and adjust as explained above
git commit
git tag

References:

D Home