tutorial how-to build your own reporter plugin

Signed-off-by: Nikola Pajkovsky <npajkovs@redhat.com>

9 files changed, 408 insertions, 15 deletions

diff --git a/Makefile.am b/Makefile.am
index 1dd3ff6c..fb4ba702 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,7 +1,7 @@
 ACLOCAL_AMFLAGS = -I m4
 SUBDIRS = lib src inc po icons
 
-EXTRA_DIST = doc/CodingStyle abrt.spec abrt.pc.in
+EXTRA_DIST = doc/coding-style abrt.spec abrt.pc.in doc/abrt-plugin/ doc/howto-write-reporter
 
 pkgconfigdir = $(libdir)/pkgconfig
 pkgconfig_DATA = abrt.pc
diff --git a/abrt.spec b/abrt.spec
index b0f22c2d..f63540f5 100644
--- a/abrt.spec
+++ b/abrt.spec
@@ -338,6 +338,7 @@ fi
 %{_includedir}/*
 %{_libdir}/lib*.so
 %{_libdir}/pkgconfig/*
+%doc doc/abrt-plugin doc/howto-write-reporter
 
 %files gui
 %defattr(-,root,root,-)
diff --git a/doc/.gitignore b/doc/.gitignore
new file mode 100644
index 00000000..4d0602d6
--- /dev/null
+++ b/doc/.gitignore
@@ -0,0 +1,2 @@
+!Makefile
+*.so
diff --git a/doc/abrt-plugin/HelloWorld.conf b/doc/abrt-plugin/HelloWorld.conf
new file mode 100644
index 00000000..cc8ba798
--- /dev/null
+++ b/doc/abrt-plugin/HelloWorld.conf
@@ -0,0 +1,8 @@
+Enabled = yes
+
+# if OptionBool is set to yes, it will print the text specified in PrintString option
+# if OptionBool is set to no, the error with the message "OptionBool is set to `no', wrong"
+# will be generated
+OptionBool = yes
+
+PrintString = "Hello World!!!"
diff --git a/doc/abrt-plugin/Makefile b/doc/abrt-plugin/Makefile
new file mode 100644
index 00000000..31eb228e
--- /dev/null
+++ b/doc/abrt-plugin/Makefile
@@ -0,0 +1,26 @@
+PROGRAM	=	libHelloWorld
+CXX	=	g++
+SRCS	+=	abrt-reporter-hello-world.cpp
+OBJS	+=	$(addsuffix .o, $(basename $(SRCS)))
+
+
+.PHONY: clean install uninstall
+
+%.o: %.cpp
+	$(CXX) `pkg-config --cflags --libs abrt` -m64 -c -Wall -std=c++98 -pedantic $<
+
+$(PROGRAM).so: $(OBJS)
+	$(CXX) -shared $< -o $@
+
+clean:
+	rm -f *.o *.so
+
+install:
+	install -m 755 -D $(PROGRAM).so /usr/lib64/abrt/
+	install -m 644 -D HelloWorld.conf /etc/abrt/plugins/
+
+uninstall:
+	rm -f /usr/lib64/abrt/$(PROGRAM).so
+	rm -f /etc/abrt/plugins/HelloWorld.conf
+
+
diff --git a/doc/abrt-plugin/abrt-reporter-hello-world.cpp b/doc/abrt-plugin/abrt-reporter-hello-world.cpp
new file mode 100644
index 00000000..30a55e88
--- /dev/null
+++ b/doc/abrt-plugin/abrt-reporter-hello-world.cpp
@@ -0,0 +1,104 @@
+/*
+    Copyright (C) 2010  ABRT team
+    Copyright (C) 2010  RedHat Inc
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License along
+    with this program; if not, write to the Free Software Foundation, Inc.,
+    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+*/
+
+#include <abrt/abrtlib.h>
+#include <abrt/abrt_exception.h>
+#include "abrt-reporter-hello-world.h"
+
+std::string CHelloWorld::Report(const map_crash_data_t& pCrashData,
+                const map_plugin_settings_t& pSettings,
+                const char *pArgs)
+{
+    if (!m_OptionBool)
+    {
+        /*
+         * Exceptions is used to notify gui/cli that something is wrong
+         * and stop reporting; gui/cli will show it as an error message.
+         */
+        throw CABRTException(EXCEP_PLUGIN, "OptionBool is set to `no', wrong");
+    }
+
+    /*
+     * Same as example above, but here we show how you can use try..catch block
+     */
+    try
+    {
+    }
+    catch (CABRTException& e)
+    {
+        //throw CABRTException(EXCEP_PLUGIN, "Oops something wrong");
+    }
+
+    /*
+     * If you want to log some information use function log.
+     * abrtd can be started as standalone application running in
+     * foreground (abrtd -d) and then you will see log information.
+     * Logging has tree levels and they are controlled by VERBx where `x'
+     * can be 1, 2 and 3. If you want to level1 (VERB1 message) run abrtd -dv,
+     * for level2 (VERB2 message) -dvv and for level3(VERB3 message) -dvvv.
+     */
+
+     VERB1 log("what you sometimes want to see, even on a production box");
+     VERB2 log("debug message, not going into insanely small details");
+     VERB3 log("lots and lots of details");
+
+    return m_PrintString;
+}
+
+void CHelloWorld::SetSettings(const map_plugin_settings_t& pSettings)
+{
+    m_pSettings = pSettings;
+
+    map_plugin_settings_t::const_iterator end = pSettings.end();
+    map_plugin_settings_t::const_iterator it;
+
+    it = pSettings.find("OptionBool");
+    if (it != end)
+        m_OptionBool = string_to_bool(it->second.c_str());
+
+    it = pSettings.find("PrintString");
+    if (it != end)
+        m_PrintString = it->second;
+
+}
+
+/*
+ * Use the macro PLUGIN_INFO in the *.cpp file of your plugin so that your
+ * subclass will be properly registered and treated as a plugin.
+ * This sets up all the lower-level and administrative details to fit your
+ * class into the plugin infrastructure. The syntax is:
+
+ * PLUGIN_INFO(type, plugin_class, name, version, description, email, www, gtk_builder)
+ *  - "type" is one of ANALYZER, ACTION, REPORTER, or DATABASE
+ *  - "plugin_class" is the identifier of the class
+ *  - "name" is a string with the name of the plugin
+ *  - "version" is a string with the version of the plugin
+ *  - "description" is a string with the summary of what the plugin does
+ *  - "email" and "www" are strings with the contact info for the author
+ *  - "gtk_builder" is path to plugins gui
+ */
+
+PLUGIN_INFO(REPORTER,
+            CHelloWorld,
+            "HelloWorld",
+            "0.0.1",
+            "Show `Hello world!!!' in gui",
+            "author",
+            "www adress to project/plugin",
+            "/path/to/gui.plugin")
diff --git a/doc/abrt-plugin/abrt-reporter-hello-world.h b/doc/abrt-plugin/abrt-reporter-hello-world.h
new file mode 100644
index 00000000..ab4220ce
--- /dev/null
+++ b/doc/abrt-plugin/abrt-reporter-hello-world.h
@@ -0,0 +1,61 @@
+/*
+    Copyright (C) 2010  ABRT team
+    Copyright (C) 2010  RedHat Inc
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License along
+    with this program; if not, write to the Free Software Foundation, Inc.,
+    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+*/
+
+#ifndef ABRT_REPORTER_HELLO_WORLD_H
+#define ABRT_REPORTER_HELLO_WORLD_H
+
+/*
+ * If you want to build reporter you have to include `reporter'.
+ * Others are analyzer.h, database.h and action.h
+ */
+#include <abrt/reporter.h>
+
+class CHelloWorld : public CReporter
+{
+    private:
+        /*
+         * In our tutorial we will have two options called OptionBool
+         * and PrintString. Daemon will load HelloWorld.conf and pass it to our
+         * SetSettings method in parsed form, allowing us to change options.
+         */
+        bool m_OptionBool;
+        std::string m_PrintString;
+
+    public:
+        /**
+        * A method, which reports a crash dump to particular receiver.
+        * The plugin can take arguments, but the plugin  has to parse them
+        * by itself.
+        * @param pCrashData A crash report.
+        * @oaran pSettings A settings passed from gui or cli
+        * @param pArgs Plugin's arguments.
+        * @retun A message which can be displayed after a report is created.
+        */
+        virtual std::string Report(const map_crash_data_t& pCrashData,
+                                   const map_plugin_settings_t& pSettings,
+                                   const char *pArgs);
+
+        /**
+        * A method, which takes settings and apply them. It is not a mandatory method.
+        * @param pSettings Plugin's settings
+        */
+        virtual void SetSettings(const map_plugin_settings_t& pSettings);
+};
+
+#endif
diff --git a/doc/howto-write-reporter b/doc/howto-write-reporter
new file mode 100644
index 00000000..abc77d5d
--- /dev/null
+++ b/doc/howto-write-reporter
@@ -0,0 +1,205 @@
+How to write your reporter plugin
+---------------------------------
+This plugin receives the entire finished crash report and posts/reports
+it somewhere (e.g. logs it, mails it, posts it on some web tool...)
+
+You have to override these methods:
+
+std::string Report(const map_crash_data_t& pCrashData,
+                    const map_plugin_settings_t& pSettings,
+                    const char *pArgs)
+
+void SetSettings(const map_plugin_settings_t& pSettings);
+- It is not a mandatory method.
+
+Example of header plugin
+------------------------
+$ cat abrt-reporter-hello-world.h
+
+#ifndef ABRT_REPORTER_HELLO_WORLD_H
+#define ABRT_REPORTER_HELLO_WORLD_H
+
+/*
+ * If you want to build reporter you have to include `reporter'.
+ * Others are analyzer.h, database.h and action.h
+ */
+#include <abrt/reporter.h>
+
+class CHelloWorld : public CReporter
+{
+    private:
+        /*
+         * In our tutorial we will have two options called OptionBool
+         * and PrintString. Daemon will load HelloWorld.conf and pass
+         * it to our SetSettings method in parsed form, allowing us to
+         * change options
+         */
+        bool m_OptionBool;
+        std::string m_PrintString;
+
+    public:
+        /**
+        * A method, which reports a crash dump to particular receiver.
+        * The plugin can take arguments, but the plugin has to parse them
+        * by itself.
+        * @param pCrashData A crash report.
+        * @oaran pSettings A settings passed from gui or cli
+        * @param pArgs Plugin's arguments.
+        * @retun A message which can be displayed after a report is created.
+        */
+        virtual std::string Report(const map_crash_data_t& pCrashData,
+                                   const map_plugin_settings_t& pSettings,
+                                   const char *pArgs);
+
+        /**
+        * A method, which takes settings and apply them. It is not a mandatory
+	* method.
+        * @param pSettings Plugin's settings
+        */
+        virtual void SetSettings(const map_plugin_settings_t& pSettings);
+};
+
+#endif
+
+Example of source code of plugin
+--------------------------------
+$ cat abrt-reporter-hello-world.cpp
+
+#include <abrt/abrtlib.h>
+#include <abrt/abrt_exception.h>
+#include "abrt-reporter-hello-world.h"
+
+std::string CHelloWorld::Report(const map_crash_data_t& pCrashData,
+                const map_plugin_settings_t& pSettings,
+                const char *pArgs)
+{
+    if (!m_OptionBool)
+    {
+        /*
+         * Exceptions is used to notify gui/cli that something is wrong
+         * and stop reporting; gui/cli will show it as an error message.
+         */
+        throw CABRTException(EXCEP_PLUGIN, "OptionBool is set to `no', wrong");
+    }
+
+    /*
+     * Same as example above, but here we show now how you can use try..catch block
+     */
+    try
+    {
+    }
+    catch (CABRTException& e)
+    {
+        //throw CABRTException(EXCEP_PLUGIN, "Oops something wrong");
+    }
+
+    /*
+     * If you want to log some information use function log.
+     * abrtd can be started as standalone application running in
+     * foreground (abrtd -d) and then you will see log information.
+     * Logging has tree levels and they are controlled by VERBx where `x'
+     * can be 1,2 and 3. If you want to see level1(VERB1 message) run abrtd -dv,
+     * for level2 (VERB2 message) -dvv and for level3 (VERB3 message) -dvvv.
+     */
+
+     VERB1 log("what you sometimes want to see, even on a production box");
+     VERB2 log("debug message, not going into insanely small details");
+     VERB3 log("lots and lots of details");
+
+    return m_PrintString;
+}
+
+void CHelloWorld::SetSettings(const map_plugin_settings_t& pSettings)
+{
+    m_pSettings = pSettings;
+
+    map_plugin_settings_t::const_iterator end = pSettings.end();
+    map_plugin_settings_t::const_iterator it;
+
+    it = pSettings.find("OptionBool");
+    if (it != end)
+        m_OptionBool = string_to_bool(it->second.c_str());
+
+    it = pSettings.find("PrintString");
+    if (it != end)
+        m_PrintString = it->second;
+
+}
+
+/*
+ * Use the macro PLUGIN_INFO in the *.cpp file of your plugin so that your
+ * subclass will be properly registered and treated as a plugin.
+ * This sets up all the lower-level and administrative details to fit your
+ * class into the plugin infrastructure. The syntax is:
+ *
+ * PLUGIN_INFO(type, plugin_class, name, version, description, email, www, gtk_builder)
+ *  - "type" is one of ANALYZER, ACTION, REPORTER, or DATABASE
+ *  - "plugin_class" is the identifier of the class
+ *  - "name" is a string with the name of the plugin
+ *  - "version" is a string with the version of the plugin
+ *  - "description" is a string with the summary of what the plugin does
+ *  - "email" and "www" are strings with the contact info for the author
+ *  - "gtk_builder" is path to plugins gui
+ */
+
+PLUGIN_INFO(REPORTER,
+            CHelloWorld,
+            "HelloWorld",
+            "0.0.1",
+            "Show `Hello world!!!' in gui",
+            "author",
+            "www adress to project/plugin",
+            "/path/to/gui.plugin")
+
+Example of configuration file
+-----------------------------
+When option 'Enabled' is missing or is set to 'no', plugin won't be loaded
+at abrtd start-up (but may be loaded later if plugin is used in one of the
+directives). If it is set to 'yes', plugin is loaded right away.
+At the plugin load time, options are parsed by daemon and passed to plugin's
+SetSettings method.
+
+
+$ cat HelloWorld.conf
+Enabled = yes
+
+# just for demonstration
+# if OptionBool is set to yes, it will print the text specified in PrintString option
+# if OptionBool is set to no, the error with the message "OptionBool is set to `no', wrong"
+will be generated.
+
+OptionBool = yes
+
+PrintString = "Hello World!!!"
+
+Example of Makefile
+-------------------
+Makefile is written to build plugin on 64bit machines. If you want to build for
+32bit get rid of -m64 in build section and rename /usr/lib64/abrt to /usr/lib/abrt
+
+$ cat Makefile
+PROGRAM	=	libHelloWorld
+CXX	=	g++
+SRCS	+=	abrt-reporter-hello-world.cpp
+OBJS	+=	$(addsuffix .o, $(basename $(SRCS)))
+
+
+.PHONY: clean install uninstall
+
+%.o: %.cpp
+	$(CXX) `pkg-config --cflags --libs abrt` -m64 -c -Wall -std=c++98 -pedantic $<
+
+$(PROGRAM).so: $(OBJS)
+	$(CXX) -shared $< -o $@
+
+clean:
+	rm -f *.o *.so
+
+install:
+	install -m 755 -D $(PROGRAM).so /usr/lib64/abrt/
+	install -m 644 -D HelloWorld.conf /etc/abrt/plugins/
+
+uninstall:
+	rm -f /usr/lib64/abrt/$(PROGRAM).so
+	rm -f /etc/abrt/plugins/HelloWorld.conf
+
diff --git a/doc/plugins-howto b/doc/plugins-howto
index 81090f33..55753a9b 100644
--- a/doc/plugins-howto
+++ b/doc/plugins-howto
@@ -81,20 +81,6 @@ dump, or all debug dumps for periodic actions.
 The second argument is a string with arguments (specified in config file).
 
 
-Reporter Plugin
----------------
-This plugin receives the entire finished crash report and
-posts/reports it somewhere (e.g. logs it, mails it, posts
-it on some web tool...)
-
-You have to override this method:
-
-virtual void Report(const map_crash_data_t& pCrashData,
-                    const char *pArgs);
-- This method takes the report and presents it somewhere to the world.
-  The second argument is a string with arguments specified for the reporter.
-
-
 Database Plugin
 ---------------
 This plugin is used to store the metadata about the crash. The metadata