Skip to content

MADARA Project Generator

Jump to bottom Edit New page
James Edmondson edited this page Apr 28, 2024 · 6 revisions

Overview

To aid in quickly creating new MADARA applications, we have created a tool called the MADARA Project Creator (mpg.pl). the tool creates a C++ project that can be used on Linux, Mac, or Windows to compile new applications, threads, transports, and filters with all appropriate libraries. On this wiki page, we'll describe the mpg.pl's core features and how you can modify and compile applications that are generated by it.

Table of Contents

Usage

Invoking $MADARA_ROOT/scripts/projects/mpg.pl with --help will list the options that are available to the mpg.pl tool. The listing includes the following:

options:
  --app|-a name             adds or updates a generated MADARA application
  --thread|t|nt name        create or use an existing custom thread
  --transport|r|nr name     create or use an existing custom network transport
  --on-send|send name       create or use an on-send filter 
  --on-receive|receive name create or use an on-receive filter 
  --path|-p|--dir dir       the directory path to create custom apps
  --verbose|-v              print detailed debug info

Generation Process

Whenever possible, options do no harm. So, if you have previously created a transport, thread, or on-send/on-receive filter, your existing source code will not be modified or overwritten. Similarly, any applications that you have previously created will be updated within the appropriate begin and end comments within the application file. Anything outside of begin and end comment lines.

The following is the begin and end lines inside of a generated application that contains a new thread called NewThread.

  // begin thread creation
  threader.run(hertz, "NewThread", new threads::NewThread());
  // end thread creation

Anything within the begin/end thread creation will be overwritten whenever the application is modified with calls to mpg.pl. Anything outside of this thread creation section is safe to modify. mpg.pl will not overwrite anything outside of its marked generation sections in an application (what you specify with --app from the command line).

By default, all apps can be configured with existing or new filters, threads, or transports by simply noting the objects you are interested in using in an app. So, when you specify a thread and a new app, the app source will be modified to include the thread header and will also launch the thread inside of the app's Threader at a user-controllable hertz rate (from the command line of your app).

About Generated Files

The mpg.pl tool generates new files that can be compiled into executable code. The location of these files is relative to the path set with --path when invoking the tool. The following shows where generated code can be found. All files in these folders are editable and future invocations of the tool will not harm your changes outside of the begin/end sections in the application files (found at the top level of the $path/src directory).

$path/src            application source files live here. Modify this file to change the main program.
$path/src/filters    source files for on-receive or on-send filters that react to network events.
$path/src/threads    source files for threads that can be run with the MADARA Threader for managing qos in threads
$path/src/transports source files for transports, including generated send code and a custom receive thread

Each app in $path/src includes some useful command line options, which you can print out with $path/bin/$app -h.

Examples

For mpg.pl generation, the only required parameter is a path. The default path is the current directory, which is a convenience. However, it is highly recommended that you first creation a new directory for your project by specifying --path my_new_dir. By doing so, the directory my_new_dir will be created for you by the mpg.pl script. The following are examples of mpg.pl usage.

Generating an App

$MADARA_ROOT/scripts/projects/mpg.pl --path new_project --app publisher

You can compile the publisher app and run it with the following:

new_project/build.sh
new_project/bin/publisher

Generating Multiple Apps

$MADARA_ROOT/scripts/projects/mpg.pl --path new_project --app publisher --app subscriber

You can compile the publisher and subscriber and run them with the following:

new_project/build.sh
new_project/bin/publisher &
new_project/bin/subscriber

Generating an App with a Thread

$MADARA_ROOT/scripts/projects/mpg.pl --path new_project --app publisher --thread NewThread

You can compile and run the publisher with the following:

new_project/build.sh
new_project/bin/publisher

Generating an App with a Transport

$MADARA_ROOT/scripts/projects/mpg.pl --path new_project --app publisher --thread NewTransport

You can compile and run the publisher with the following:

new_project/build.sh
new_project/bin/publisher

Generating an App with a Send Filter

$MADARA_ROOT/scripts/projects/mpg.pl --path new_project --app publisher --send NewSendFilter

You can compile and run the publisher with the following:

new_project/build.sh
new_project/bin/publisher

Generating an App with a Receive Filter

$MADARA_ROOT/scripts/projects/mpg.pl --path new_project --app subscriber --receive NewReceiveFilter

You can compile and run the subscriber with the following:

new_project/build.sh
new_project/bin/subscriber
Add a custom footer
Add a custom sidebar
Clone this wiki locally