Skip to main content

OxOOL Module Compiling HOWTO

1. Preparing The Environment

  • Follow the instructions of OxOOL Community Compiling HOWTO to compile oxool-community -- English version coming soon

    • Be noticed that you should use autogen.sh and don't directly run configure here. autogen.sh by default would add enable-debug and load ModuleTesting module for developing and test modules.

  • Generate oxool and oxool-dev rpm/deb packages by rpmbuild or debuild.

Install oxool and oxool-dev you just generated into your development environment. oxool-dev contains the headers necessary for building modules, module templates and oxool-module-maker which will make it a lot easier to start a new module.

2. Create an basic module repository by oxool-module-maker

  • Run oxool-module-maker to create a module git repository from a module template. The parameters are:

    • --module-name=name : Module name, used for the git repository name. It must match the regular expression: ^[\w\@#]+$ which means all the upper and lower case letters, number 0-9, underline _ and # @ symbols. Notice that dash '-' is not allowed due to C++ class naming issue, and underline '_' is better not used.

  • --serviceURI=serviceURI : URI used by this module. If it ends with a slash '/' it means this module can handle a series of related commands. For example, "/oxool/user/" means this module is used to handle requests such as /oxool/user/add, /oxool/user/del, /oxool/user/update, and so on. Without the ending slash means it is a fixed URI.

--version=version : Version number. Default "0.0.1"。

--summary=summary : Specify Summary field, used in Summary fields in generated rpm file.

--description=Description : Specify Description field, used in Description fields in generated deb file.

--author=author : Module author. By default it will use the user.name and user.email in global git settings.

--license=license : Module license. Default "MPLv2.0".

--adminPrivilege=true/false : Does this module URI needs admin privileges? Default "false".

--adminIcon=icon : The icon used in backend administration page (See getbootstrap.com for references.) Default "bug-fill".

--adminItem=text : The text/title used in backend administration page.

--template-path=path : Assign the module template path. The new created module will be generated by copying files from this path. By default the module template is in /usr/share/oxool-devel/module-template.

--output-path=path : The path of generated module. By default it will be in user home directory. Notice that it may cause problems if you use symbols like ~ so better use a full path name.

Example:

oxool-module-maker --module-name="samplemod" --serviceURI="/oxool/samplemod/" --summary="A sample moudle service on OxOOL" --description="A sample module service on OxOOL" --output-path="/home/oxool/git"
  • A new git repository will be generated in the specified output-path. Inside the folder are all the files from the specified template-path folder.

3. Compile and Test Modules

  • Use autogen.sh to generate configure, then run configure to check the environment and generate Makefile.

Compile with make.

Before testing the module, go to oxool-community folder and run make run to activate a testing oxool environment. Notice that when you install oxool packages in your environment, it will activate a systemd service oxool.service and occupy the default port like 9980. So you may need to deactivate this systemd service by sudo systemctl stop oxool before running the testing oxool environment.

After starting the testing environment, go back to the module folder and run ./test.sh <XML file for this module>. test.sh will call ModuleTesting module in oxool and sent the XML path to it. ModuleTesting will then notify oxool to load the .so file of this module (under .libs/ of the module folder). Now you can call and run the module by calling the URI specified in serviceURI. For example, open your browser with http://127.0.0.1:9980/oxool/samplemod/ .

If you change something in the module, you need to re-compile the module and re-run test.sh to load the new .so into oxool to make it effect.

Back to top