Skip to content

Contribute

Jump to bottom Edit New page
it4e edited this page Feb 26, 2017 · 10 revisions

CHL is an open-source library, which essentially means that anyone may contribute to the source code. There are several ways you can contribute to CHL. In the issues page you can view all features, bugs and fixes that are waiting to be properly coded. Do you, however, have your own idea of an useful feature that may fit into CHL, do not hesitate to write it.

Contributing to CHL is very straight-forward, and if you have ever used Github before it should feel familiar. Below is a guide on how CHL features are written, and which regulations you must follow, as well as a guide on how contributions to CHL are made.

It is recommended that you have read the tutorial before contributing.

Contents

Contributing to CHL

Bugs, Fixes and Improvements

Features and Plugins

Contributing to CHL

Github provides you with all the tools you need to make proper and successful contributions to the CHL repository.

1. Forking Repository

First of all we will need to grab a copy of the official CHL repository so we can freely make changes to the code. This is done by something called forking, which essentially means that you get your own personal copy of the CHL repository.

Visit the CHL repository page on Github, hit the fork button and you are good to go. There should now be a repository named 'CHL' under your own repositories.

2. Pull Requests

Once you have made any changes to your own copy of CHL, and want them to be uploaded to the main CHL repository you can do so by sending a pull request. This request will be sent to the administrator for inspection, and he may or may not merge your code with the official code.

To send a pull request you just hit the button saying 'New pull request'.

Bugs, Fixes and Improvements

You can view all of the things that needs a little bit of tweaking in the issues page. Once you have made any improvements or changes to the code you should issue a pull request and wait for the administrator to review your code. If the code is good and is working correctly, it will most certainly be publicly merged to the main CHL repository.

See: contributing to CHL.

Features and Plugins

When constructing new features and plugins for CHL there are a few regulations and standards you must follow. These are things like directory and file structure, rules for function names and rules for usage of external libraries other than 'libchl'.

Directory Structure

In the CHL repository there is a folder named plugins, which contains all of the CHL plugins. To start off with creating a plugin for CHL, you should initialize a folder with the name of the plugin inside of the plugins directory.

mkdir chl/plugins/plugin_name

This folder will contain all of the files related to the plugin.

Inside of your newly created folder you should create two additional folders.

src: will contain all of the source files and non-applicable header files.
libs: will contain any external libraries that are needed. (Make sure you put a .gitignore file inside libs, so git does not ignore it).

When I say that the src folder should contain only the non-applicable header files, I mean the header files declaring all of the functions and variables in the source files. You will be creating a separate header file for all of the functions only made for production, which will be put directly into the plugin folder.

Makefile (Compilation of source files)

You should also create a makefile in your main plugin directory. This makefile should compile all of the source files of src/ and move the object files to a folder called cmp located right in the root folder of chl (created by CHL automatically at compile time). The makefile is then executed by the CHL install script.

Make sure you are compiling the source files using the -c, -Wall, -Werror, -fPIC flags. These are required for the object files to work with the final library.

Example compilation

gcc -c -Wall -Werror -fPIC src/*.c
mv *.o ../../cmp

plugins/plugin_name/

  • src/
  • libs/
  • makefile
  • production_header.h
  • ....

Rules and Regulations

These are the rules and regulations you must follow when constructing plugins for CHL.

  • The code should be well-commented and documented, and the functions as self-descriptive as possible.

  • Non-applicable functions which will not be used in production may take any name, but when it comes to functions made for production the name must start with the 'chl_' prefix. For instance chl_mysql_connect.

  • There must be exactly one header file per source file, declaring all the functions and objects inside the source.

  • There must be exactly one header file for production, which should be put directly into the plugin folder. This header file may only contain functions following the above regulation stating that functions must be prefixed with 'chl_'.

Once you have created your plugin, or made any changes to it, send off a pull request.

See: contributing to CHL.

CHL, 2022

As CHL is open-source, people are able to contribute with their own APIs, plugins and code which means that CHL is constantly upgraded and provided with new features. Do you have an idea for a new CHL feature and want to contribute?

See contribute.

Setup. API. Tutorial. Examples. FastCGI.

Clone this wiki locally