Getting Started
We've tried to make getting started with MADARA for multi-agent programming as easy as possible. Installation and update is usually as simple as one line on a command line terminal. You can program with reactive or declarative paradigms, use real-time scripting languages, and built-in containers for C++, Java, and Python. But how do you get started? Let's get you going with your first programs.
Our recommendation is to use Linux as an operating system and use the Linux build scripts. They're used by our most concentrated user base. The main question you want to ask yourself is what all do I really want to install? because MADARA and GAMS have a lot of features. So, let's go over a common install. How about installing MADARA and GAMS with UDP and ZMQ networking transports that are SSL-capable?
export CORES=4
export GAMS_ROOT=$HOME/gams
cd $HOME
$GAMS_ROOT/scripts/linux/base_build.sh prereqs madara gams zmq sslIn the above, we set CORES to 4 to say we want to build with 4 threads for speed. We set GAMS_ROOT to our home directory and a new gams directory, move into the home directory, and install all of our prerequisites and software. It should be as simple as that.
MAKE SURE YOU FOLLOW THE DIRECTIONS AND UPDATE YOUR BASHRC FILE!
To update, you can either run what you did earlier or add the noclean option to the base_build.sh command. If you want to see help for what all base_build.sh supports, try help or --help.
Ludicrous Speed Update Example
export CORES=4
export GAMS_ROOT=$HOME/gams
cd $HOME
$GAMS_ROOT/scripts/linux/base_build.sh prereqs madara gams zmq ssl nocleanEssentially, noclean tells the build system that you don't want to remove previous object files and want to use make depend to track any changes. This is appropriate if you haven't changed any build options since you last built. If your MADARA or GAMS installs malfunction, you may want to try removing the noclean option and building fresh, but the noclean option is a great way to have fast builds and works for almost all users.
We've recently updated the base_build.sh script to auto-build the last successful build you performed that did not involve noclean but with the addition that it will compile everything with noclean, i.e., we will try to perform the fastest possible rebuild without removing the old object files and taking advantage of make depend. This is a helpful way to quickly update your last build with all of the same features.
export CORES=4
export GAMS_ROOT=$HOME/gams
cd $HOME
$GAMS_ROOT/scripts/linux/base_build.shThe only time you need to redo the args is if you need to change MADARA or GAMS features. To check if you have done a successful build since this auto-upgrade feature was implemented, look at $GAMS_ROOT/last_build.lst. If the file contains options separated by newlines, then you have run GAMS with a full build since this feature was enabled. Only builds without noclean will be saved to last_build.lst
There are three solid ways to make a MADARA or GAMS application with all of the libraries and dependencies linked appropriately. The first way is to use the MADARA Project Generator script to generate a custom MADARA project with makefiles to help you build projects and add threads, transports, or filters. The second way is the $GAMS_ROOT/scripts/projects/gpc.pl script to generate a custom controller with a MakefileProjectCreator build system that can target builds to Windows, Linux, and Apple. However, this can also create a lot of scaffolding and command arguments that you don't need. The third common option is to create a custom application and Makefile yourself (for Linux) or a Visual Studio project (Windows).
This method is covered more extensively in the MADARA Project Generator wiki. Essentially, the mpg.pl is a script that generates make files and MADARA objects/applications according to parameters that you specify on the command line. To create and execute an example application, you can do the following (assuming you have installed MADARA and set your environment variables appropriately with LD_LIBRARY_PATH, especially).
$MADARA_ROOT/scripts/projects/mpg.pl --path new_project --app publisher
new_project/action.sh compile
new_project/bin/publisher
The gpc.pl generator should have the most up-to-date generation and compilation process. It is covered in various places including the Youtube Tutorial Series, created by SEI at CMU.
Generating an Agent Controller
Let's get right into an example that generates and builds everything you need
$GAMS_ROOT/scripts/projects/gpc.pl --path container_test --container MyContainer
container_test/action.sh compileBelieve it or not, you just compiled a custom GAMS and MADARA controller. This controller can be found in the container_test/src/controller.cpp,nc and it has all kinds of command line arguments you can play with to configure your agent. These include different networking transports, checkpoint saving options, etc. Play around with it and see what you can do.
For information on how to change your project/workspace to accommodate other libraries, see Module 3 of the Youtube tutorial series.
At minimum, custom Makefiles for MADARA-only projects should include the following:
- includes:
$MADARA_ROOT/include,$CAPNP_ROOT/c++/src,$BOOST_ROOT(on Linux, may be in system paths) - library path:
$MADARA_ROOT/lib,$CAPNP_ROOT/c++/libs,$BOOST_ROOT_LIB(On Linux, may be in system paths) - libraries:
MADARA,capnp,capnp-json,kj,boost_system,boost_filesystem
Once you've setup your VS solution or Makefile for the above, then you can write your first application. Let's do that now and call it the typical hello_world.cpp.
#include "madara/knowledge/KnowledgeBase.h"
// namespace shortcut (these can be really helpful in MADARA)
namespace knowledge = madara::knowledge;
int main (int argc, char ** argv)
{
knowledge::KnowledgeBase kb;
kb.set ("greeting", "Hello, World!");
kb.print ();
return 0;
}The above application creates a MADARA KnowledgeBase, saves a variable called greeting with the value Hello, World! and then prints out the greeting. You're well on your way to making your first multi-agent system! Continue on with the C++ guide.