Dodo doc > Source Files > Structure of Dodo Files

Structure of dodo files

A dodo file can be generic, with its parts separated with section tags, or specialised, where the type of the top level depends on file extension.

The file extension of a generic dodo file is .do or .dodo. The possible sections of a generic file, as well as the possible specialised files, are listed below.

Rationale: using separate files is generally more modular, but writing a single file with more than one section is useful for quick prototyping and has scoping implications as we will see later on.

Module

A dodo module regroups variables, types and functions which are related. It can be divided into a header and a main body. A module is introduced with the section tag:

__Module__ name (version: "version string")

Header

A module header declares an interface for the module. Its declarations should have an implementation, either in the header itself or in the body. It is the public part of a module.

A module header is introduced with the section tag:

__Header__

It can also be written as a specialised header file with extension .doh or .dodoh. In that case the name of the module is the name of the file.

Rationale: declaring the interface separately from the implementation helps documenting the code, encourages proper encapsulation, and since everything is public there is no need for visibility specifiers. The option to write the implementation in the header itself is convenient when visibility does not matter, it avoids creating two separate module files but is considered bad style.

Main body

A module main body contains the implementation of the variables, types and functions part of the module. Its contents cannot be imported into another file. It is the private part of a module.

A module main body is introduced with the section tag:

__Main__

It can also be written as a specialised main body file with extension .doo or .dodoo. In that case the name of the module is the name of the file.

Rationale: a separate module body lets the developer hide the details of the implementation, or offer alternative implementations for a same module.

Library

A library regroups the interfaces of one or more related modules for external use. Existing symbols are exported with the __export directive. Additional declarations can also be marked for export using the __public tag.

A library can contain initialisation code that executes when it is loaded. Any declaration or implementation which is not preceded with __public or exported using __export will not be visible externally.

A library is introduced with the section tag:

__Library__ name (version: "version string")

It can also be written as a specialised library file with extension .doa or .dodoa. In that case the name of the library is the name of the file.

Rationale: a library allows to pick and match declarations from different modules, and group them together in a convenient package. A library can be the best destination for initialisation code.

Service

A service offers the same services and uses same export rules as a library, but it also manages resources which can be accessed with the help of capabilities. A service typically runs in its own thread.

A service is introduced with the section tag:

__Service__ name (version: "version string")

It can also be written as a specialised file with extension .dos or .dodos. In that case the name of the service is the name of the file.

Rationale: by offering an infrastructure to manage securely and safely resources, dodo aims to minimise bugs and maximise interoperability. The needs of a service are similar to a library, hence it uses the same syntax for exports.

^ 1. Source Files

v 1.2. Use of Modules