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 existing C libraries. Since D is binary compatible with C ABI code, this makes a wealth of existing functionality available in D with limited effort. 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/ -L-lssl ...

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.

  1. Initialize the repository
  2. git init
    touch README.md
    git add README.md
    git commit
    
  3. Add the plain C header files in branch C
  4. git checkout -b C
    mkdir C/
    cp -a path/to/include/files/* C/
    git add C/
    git commit
    
  5. Merge branch C and copy C header files to deimos/
  6. 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

    E.g. the header file llvm-c/Analysis.h will get the module name deimos.llvm.c.analysis and foo/bar/if.h will get the module name 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.

  7. Changing the contents of each module
  8. 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,

  9. Tag with library version
  10. Tag the commit of the finished translation using the same version string as used by the C library.

    git tag 3.1 <commit>
    

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.

Handling multiple versions

When translating multiple versions of a C library each translation must be tagged with its appropriate version. Each version should have its own branch to ease updating/fixing a translation. The master branch is the translation of the latest version.

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 -f <old_tag>

References:

Forums | Comments | Search | Downloads | Home