rename and lower-case doc files

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

1 files changed, 155 insertions, 0 deletions

diff --git a/doc/plugins-howto b/doc/plugins-howto
new file mode 100644
index 00000000..81090f33
--- /dev/null
+++ b/doc/plugins-howto
@@ -0,0 +1,155 @@
+This document describes how to create your own plugin for abrt.
+
+Although a base abstract class CPlugin exists, you can't inherit
+directly from it. You must use one of the four subclasses,
+depending on what you want your plugin to do.
+
+The subclasses are:
+    * Action plugin (CAction)
+    * Analyzer plugin (CAnalyzer)
+    * Reporter plugin (CReporter)
+    * Database plugin (CDatabase)
+
+Each of them requires you to override a different set of methods.
+
+The pDebugDumpDir parameter is very common: it specifies the directory
+that is created to gather information of this specific crash.
+The files that were created when the application crashed (such as core dumps)
+are all stored here. In addition, the plugins can write
+their output files there, if any.
+
+Plugin types in detail:
+
+
+Analyzer Plugin
+---------------
+Crashes differ, depending on where they occur, for example crashes
+in the kernel differ from crashes in userspace binaries, which differ
+from crashes in python scripts. Therefore, there is a plugin
+for each type of application that you want abrt to handle.
+
+You have to override these methods:
+
+virtual std::string GetLocalUUID(const char *pDebugDumpPath);
+- This method is invoked immediately after crash is detected
+  and its data is saved by the corresponding hook.
+  It needs to compute an unique hash (UUID) of the crash.
+  When a crash occurs and abrt finds an earlier crash with the same
+  UUID, new crash is discarded as a duplicate, it doesn't show up
+  in abrt's crash list, but instead a crash count for the earlier
+  crash is incremented.
+
+virtual void CreateReport(const char *pDebugDumpDir, int force)
+- This method is called when user wants to report a crash
+  ([Reoprt] button in GUI, etc). Analyzer can perform additional,
+  more CPU/disk intensive, or interactive processing at this point.
+  For example, CCpp plugin's CreateReport() processes coredump file,
+  produces a textual backtrace, and saves it to crash dump directory.
+
+virtual std::string GetGlobalUUID(const char *pDebugDumpPath);
+- This method computes a "duplicate hash" which is used search for
+  duplicates in remote bug databases such as Bugzilla. They are
+  "less unique" than LocalUUIDs: ideally, the same crash
+  on different architecture or with slightly different backtrace
+  will still have the same GlobalUUID.
+  [TODO: renaming it to DUPHASH]
+
+
+Action Plugin
+-------------
+This type of plugin is useful when you need some action to be performed.
+Action plugins can be invoked in three ways:
+
+* Immediately when a crash is encountered (using ActionsAndReporters = ...
+  directive in abrt.conf). These action plugins are run on every crash
+  (regardless of crash type).
+
+* After Analyzer plugin processed a crash (by specifying plugin in
+  [AnalyzerActionsAndReporters] section, for example: "CCpp = AnActionPlugin").
+  In this case, action plugin's Run() method will be run after analyzer
+  plugin's CreateReport() and GetGlobalUUID() methods have finished.
+
+* If you need some action to be performed periodically ([Cron] section
+  in the same file).
+
+You have to override one method:
+
+virtual void Run(const char *dir, const char *args);
+
+The first argument is a directory that contains the current debug
+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
+has to be in a database, to distinguish whether the current crash is or
+is not the same as some crash before. The database can be local, or in
+some centralized location on the network.
+
+You have to override these methods:
+virtual void Connect();
+virtual void DisConnect();
+- connect and disconnect from the database
+
+virtual void Insert(const std::string& pUUID,
+                    const std::string& pUID,
+                    const std::string& pDebugDumpPath,
+                    const std::string& pTime);
+- insert an entry into the database: you use both UID (user ID) and UUID
+  (ID of the crash)
+
+virtual void Delete(const std::string& pUUID, const std::string& pUID);
+- delete an entry
+
+virtual void SetReported(const std::string& pUUID, const std::string& pUID);
+- insert information into the database to say that this bug was already
+  reported (so for example the report plugins won't run several times
+  for the same bug)
+
+virtual const vector_database_rows_t GetUIDData(const std::string& pUID);
+- get database rows for the specified user ID
+
+virtual const database_row_t GetUUIDData(const std::string& pUUID, const
+ std::string& pUID);
+- get a database row for the specified user ID and UUID
+
+
+The macro PLUGIN_INFO
+---------------------
+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)
+- "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
+
+For example:
+PLUGIN_INFO(REPORTER,
+            CMailx,
+            "Mailx",
+            "0.0.1",
+            "Sends an email with a report via mailx command",
+            "zprikryl@redhat.com",
+            "https://fedorahosted.org/crash-catcher/wiki");