Deimos

From D Wiki
Revision as of 02:52, 27 November 2018 by D user (talk | contribs) (Category:Binding)
Jump to: navigation, search

Deimos is an endeavor to host and maintain D bindings for popular libraries and projects, notably which have a C ABI.

The original proposal for Deimos can be found in DIP12.

Rationale

Having a central place for bindings allows them to be:

  1. easily discovered;
  2. maintained by the community, even past the original author's interest in the project.

Agreeing on a common layout and conventions will also make usage and contribution easier.

Description

A repository for each project is created under https://github.com/D-Programming-Deimos. It should have the following directory structure:

|--- library name (repository root)
    |--- README.md
    |--- dub.sdl
    |--- C
        |--- foo.h
        |--- bar
            |--- baz.h
    |--- deimos
        |--- foo.d
        |--- bar
            |--- baz.d

The C directory should contain a copy of the original C headers that were translated. Doing so allows updating them to newer versions easily, as only the diffs between the old and new C headers need to be translated and applied to the D bindings.

The layout of the C directory corresponds to /usr/include on UNIX machines. Thus, if a C header file would be installed to /usr/include/bar/baz.h, in the repository it should be added as C/bar/baz.h.

The D module/package names should map such that #include <path/to/header.h> should correspond to import path.to.header;.

The D import files should try to do as least modifications as possible to simplify updates of the C headers. This includes leaving comments intact (unless e.g. adapting them to DDoc syntax).

Translated header should not require linkage of any D binary. Macros can be written as templates, e.g.:

C: #define GET(x) x.value
D: int GET(X)(X x) { return x.value; }

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

The copyright for the D import files should match the one being used by the C header as they constitute a derived work.

If the C header file has a name that is a D keyword, an underscore will be appended to the D module name.

If a C type name matches a C function name (stat), the type name will have a "_t" appended.

Recommendations

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 under an examples directory.

Submitting

To propose a new binding project to be added to Deimos, contact a member of the D-Programming-Deimos organization:

https://github.com/orgs/D-Programming-Deimos/people

If you are already a member of D-Programming-Deimos, consider making your membership public, so that you can be contacted by submitters.

Contributing

To submit updates or improvements, send a pull request as usual.

If you get no response to your pull request, or if you would like to be added as a project maintainer, ping an organization member.