[beast: 2/31] HACKING.md: document the first things to know for hacking the code base

[Tim Janik <timj src gnome org>]

commit 174c23e5ead15d05a6536ebbe9882bf9402382b6
Author: Tim Janik <timj gnu org>
Date:   Thu Jun 11 22:36:47 2015 +0200

    HACKING.md: document the first things to know for hacking the code base

 HACKING.md  |   49 +++++++++++++++++++++++++++++++++++++++++++++++++
 Makefile.am |    7 ++++++-
 2 files changed, 55 insertions(+), 1 deletions(-)
---
diff --git a/HACKING.md b/HACKING.md
new file mode 100644
index 0000000..e79848f
--- /dev/null
+++ b/HACKING.md
@@ -0,0 +1,49 @@
+% BEAST/BSE HACKING
+
+The Beast + BSE code base origins date back to the 90ties, so hacking on it
+requires some knowledge about ancient aspects and mixings with newer
+technologies. The following gives a high-level overview of the pitfalls
+involved, this file can be discussed at beast gnome org 
+
+Migrations
+==========
+
+The code base is currently undergoing several migrations and new developments:
+
+IDL-Migration
+-------------
+**[STARTED]** Move from PROC files to IDL files and later move from sfidl to AIDA IDL (aidacc, distributed 
with Rapicorn). BSE already contains an AIDA style IDL file with C++11 objects that can be used in Beast. 
Eventually, all BSE idl files need to be ported to AIDA IDL.
+
+CXX-Migration
+-------------
+**[PLANNED]** Move from GObject (BseObject) to AIDA C++11 objects, derived from Aida::ImplicitBase and 
specified in IDL files. The following steps are planned:
+* bse_object_new is used everywhere instead of g_object_new.
+* *bse_object_new* creates the BseObject/GObject and then the IDL based C++ object. Back pointers are 
installed to link the two together. That way features can be migrated incrementally from BseObject to 
CxxObject. The C++ objects auto-convert to their BseObject counter parts. This allows *base* object types to 
be replaced by CxxObjects quickly.
+    * First, signals should be migrated, as signals are the the main tie to libgobject.so.
+    * Second, once all signals are converted, all g_signal_ related code is eliminated from BSE and SFI, 
bse_proxy_connect will be removed.
+    * Last, all g_object_ and g_type_ calls can be replaced.
+
+Rapicorn-Migration
+------------------
+**[PLANNED]** Migrate the use of the Gtk+ toolkti to use Rapicorn widgets instead.
+
+Python-REPL
+-----------
+**[PLANNED]** Add interactive REPL loop via Python interpreter, requires
+integration of multiple main loops.
+
+Python-Scripting
+----------------
+**[PLANNED]** Use Python scripts instead of Scheme scripts. As soon as it's
+possible to implement basic Python scripts, SCM scripts may be broken and
+shall be replaced.
+
+Plugin-Merging
+--------------
+**[STARTED]** The BSE plugin API has allmost no uses, but pluging loading
+causes major slowdowns in the startup phase. As a consequence, all plugins
+shipped together with BSE should be linked into the same ELF library.
+
+C++11-Compilation
+-----------------
+**[COMPLETE]** Turn all .c files into .cc files so C++11 can be used everywhere.
diff --git a/Makefile.am b/Makefile.am
index a7c43a4..8d3951c 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -3,7 +3,12 @@ include $(top_srcdir)/Makefile.decl
 
 SUBDIRS = . data sfi bse plugins drivers shell beast-gtk launchers library tools po tests docs
 
-noinst_DATA =
+noinst_DATA = HACKING.html
+
+%.html: %.md
+       pandoc -s --toc -N -S -f markdown_github+pandoc_title_block -t html --email-obfuscation=javascript \
+         $< -o xgen-$(@F)
+       mv xgen-$(@F) $@
 
 # require automake 1.9
 AUTOMAKE_OPTIONS = 1.9 dist-bzip2 no-dist-gzip -Wno-portability