Documentation

Developer Guide

Welcome to the developer documentation of compil - a language-neutral, platform-neutral, toolset-neutral, technology-neutral extensible way of defining data models, component interfaces and others.

This documentation is aimed at developers who want to use compil in their applications. This overview introduces compil and tells you what you need to do to get started.

What is compil?

Compil, which is short for compile and at the same time is an abbreviation for Component Interface Language, provides a flexible, efficient, automated mechanism for defining data model and component interfaces. Think about COM, but smaller, faster, language-neutral, platform-neutral, toolset-neutral, technology-neutral. You define your data model and/or component interface once, then compil will generate for you source code in variety of languages and based on different technologies.

How it works?

You specify how your data model or component interface looks like using an idl language - compil - in .compil files. Here is a very basic example a .compil file that defines a structure containing information about a employee:

structure PhoneNumber
{
    enum PhoneType
    {
        mobile;
        home;
        work;
    }
    
    string number;
    PhoneType type = home;
}

structure Person
{
    string name;
    integer id;
    string email = optional;

    vector<PhoneNumber> phone;
}

structure Employee inherit Person
{
    string occupation;
}

As you can see, the structure format is simple - each structure has zero or more uniquely named fields, each field has a type, and optionally a default value. You can find more information about writing .compil files in the Compil Language Guide.

Once you've defined your structures, you run the compil compiler for your application languages on your .compil files to generate source code that handle the described. These provide a number of features like simple accessors for each field.

Why not just use JSON, XML, protocol buffers or thrifty

Compil is not limited to providing data serialization. It uses the code generation to create a fully functional data model and component interfaces which provides:

• Consistency and traceability between the model and the implementation
• ...

A bit of history

Before compil was born I worked with Citrix Online division of Citrix Systems on a project that I called RPCGenerator. It was a project that replaced hundreds of thousands of manually maintained lines of code with a generated code based on irpc meta declaration. This project opened my eyes for the power of code generation and its main limitations.

I stated compil with the goal to prove that most of them are not problems with the generation itself, but with how it is executed:

• Readability of the generated code - a lot of people believe that the generated code is hard to read and debug if needed. Compil generates code that is extremely human readable, well documented and even extremely well aligned. What is more, compil is configurable to support many different naming conventions.
• Risk to stuck because a particular feature is not supported - Compil is designed to allow a custom code to be seamlessly integrated into the generated code. This allows developers to extend the generated code with whatever they want. Additionally, because the code is human readable you could always abandon the generation and start maintaining it manually from this point on.
• Least Common Denominator - a lot of people complain about multi-something systems that this makes the result limited to the least common denominator for all the systems involved in the project. One example of this is unsigned integers supported in C++ but not in Java. This may look like not a serious problem but if somebody uses protocol buffers and STL at the same time will know how annoying something like this could be. Compil is designed to address all specifics to the languages as best it could be. Based on configuration the features supported by compil could be limited to ensure language compatibility.
• Enforce technologies - based on configuration compil will generate code that is compatible with the technology your project already depends on.
• Utilize technologies - The opposite of enforcing technologies is not utilizing the correct ones. Again based on configuration the generated code could use technologies of your choice. This will eliminate the need of adapting back and forth all the structures generated by compil to the technologies you are using. If you ever had a QT project that utilizes protocol buffers as a rpc serialization you know what I am talking about.

... and last but not least

• Unreasonable management - in many cases the companies are structured in a way where most of the managers are in situation that makes them to choose not the most promising approach, but the safest. Code generation is not and probably will not be considered a safe approach in the near future. Many times code generation will be rejected just because the management want to play safe. Compil is designed with this situation in mind. It is extremely flexible to allow you to be able to generate parts of your project without the need of disclosing it. Believe me there is no manager that will complain about your extreme performance.