diff options
-rw-r--r-- | Makefile.am | 2 | ||||
-rw-r--r-- | abrt.spec | 1 | ||||
-rw-r--r-- | doc/.gitignore | 2 | ||||
-rw-r--r-- | doc/abrt-plugin/HelloWorld.conf | 8 | ||||
-rw-r--r-- | doc/abrt-plugin/Makefile | 26 | ||||
-rw-r--r-- | doc/abrt-plugin/abrt-reporter-hello-world.cpp | 104 | ||||
-rw-r--r-- | doc/abrt-plugin/abrt-reporter-hello-world.h | 61 | ||||
-rw-r--r-- | doc/howto-write-reporter | 205 | ||||
-rw-r--r-- | doc/plugins-howto | 14 |
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 @@ -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 |