Develop/CodeOrganisation

How is the EasyPush source code organised?

  1. How is the EasyPush source code organised?
    1. Layout of the EasyPush source code
    2. The bin directory
    3. The cgi directory
    4. The css directory
    5. The error directory
    6. The etc directory
    7. The firewall directory
    8. The js directory
    9. The libs directory
    10. The package directory
    11. The tmpl directory

So - you've just downloaded the EasyPush source code and need a quick overview of how the code is organised? You've come to the right place. This article explains how to navigate the EasyPush source code, modify it and add to it.

Layout of the EasyPush source code

EasyPush consists of CGIs written mostly in C, the user interface written using HTML, JavaScript and CSS. The firewall code is written in Bash, while the Timezone configuration code is in Perl.

The CGIs are designed to work as front-ends to functions written in the backend libraries which carry out the actual actions. The CGIs use a templating library called  Flate

to make CGI development easy and clean by separating the HTML content

from code and storing in separate "template" files. Hence, the CGIs are also accompanied by corresponding templates which almost look like HTML markup. These are rendered into HTML by calls to functions in the Flate library from the CGIs.

Some EasyPush components can be configured using configuration files. EasyPush source code ships with some example configuration files containing recommended defaults.

The bin directory

The bin directory contains the code for helper binaries and scripts which accompany the CGIs. These binaries and scripts can be categorized into two categories:

  • Programs that are executed by the CGIs and are exclusively meant to ease the extension of the CGI's functionality.

Example: Scripts called after user addition or deletion

  • Programs that are directly executed to perform specific dedicated functions.

Example: The script that cleans quarantined emails

Read more details about the bin directory.

The cgi directory

The cgi directory contains the C code for the CGIs. Each module on the interface has its own sub-directory here.

More details about the cgi directory.

The css directory

The CGI's depend on HTML templates to render the user interface. The looks of the UI (colours, font-styles, spacing, styles) are specified using stylesheets. The css directory contains these stylesheets.

The error directory

While designing EasyPush, we've done our best to separate content and user interface from code. Just as our there is no HTML markup in our CGI or backend library code, the text of all error messages displayed in EasyPush are also not stored inside the code.

When an error occurs during the execution of any back-end library or CGI code, an error code is returned by the function. These error codes are defined as a macros in a separate header file. The CGI uses a common function that retrieves a human readable error message corresponding to the error code and displays it on the interface.

These human readable error messages corresponding to the error codes are stored in this directory. The error code is the name of the file while the file's contents are the error message.

The etc directory

The etc directory is where we store EasyPush-specific configuration files and directories.

You can read more details about the configuration stored in the etc directory.

The firewall directory

deepOfix ships with a rather elaborate, yet easy-to-configure firewall system. This firewall is meant to protect a deepOfix server - from the Internet and from your LAN(s).

The firewall directory contains the scripts and configuration for the deepOfix firewall.

More details...

The js directory

EasyPush uses the in-browser JavaScript code to perform a lot of visual and UI enhancement and validation functions. The JavaScript code of the web interface is stored in this directory. These are included into the HTML templates.

Descriptions of various EasyPush-specific JavaScript code?

The libs directory

All along EasyPush has had two levels of code abstraction. All system-specific code is compiled as shared object libraries. This code needs to have no knowledge or awareness of the user interface and just exports a set of functions that are used by CGIs (and command line utilities) to perform specific tasks. Similarly, all UI specific code and CGI code is written separately.

Hence someone focusing on writing EasyPush front-end CGIs needs no knowledge of how things work on the system side.

The libs directory contains libraries of C functions that carry out the back-end system tasks (like operating on the OpenLDAP server or managing services or creating mailboxes and so on). All the modules are segregated into directories named after them.

The package directory

The package directory contains files needed for creating a .deb binary package of EasyPush. We use the  ESP Package Manager (EPM) to create and maintain the EasyPush binary package. Most of the files in this directory are dynamically generated whenever the bin/make_deb script is called. (Remember that this script has to be executed in the main EasyPush trunk directory).

The tmpl directory

The CGIs use the Flate templating library to separate the HTML layout from the program logic. The tmpl directory stores the HTML user interface templates corresponding to the CGIs. Again, these are segregated into directories according to their respective modules.