Debian specifics

diff --git a/debian/README.Debian b/debian/README.Debian
new file mode 100644 (file)
index 0000000..1141dee
--- /dev/null
+++ b/debian/README.Debian
@@ -0,0 +1,76 @@
+JUCE for Debian
+===============
+
+upstream's preferred form of usage of JUCE is to include a verbatim copy of all
+used JUCE modules in your appication.
+This is made explicit in the 'Introjucer', JUCE's own software project
+management workbench, that will copy (or symlink, or include otherwise) the
+modules' source code into your project.
+
+For various reasons, Debian frowns upon static linking for distributed packages
+and instead encourages dynamic linking (see [1] for a discussion).
+
+Therefore, JUCE for Debian is built as a library ("libjuce") that has all
+(possible) features enabled.
+Debian packages of software that uses JUCE are encouraged to use this library.
+
+[1] https://wiki.debian.org/StaticLinking
+
+
+# Introjucer for Debian
+
+If you are developing your own JUCE application, you are of course free to
+follow upstream's advice.
+Installing the following packages will give you the 'Introjucer' as Debian
+packages while keeping your embedded-module-code workflow:
+ - juce-utils (contains the Introjucer)
+ - juce-modules-source (contains the source-code for the JUCE modules)
+
+The 'Introjucer' as shipped with Debian has the following modification regarding
+the once shipped by upstream:
+
+- The generated project Makefile will honour external *FLAGS (e.g. CXXFLAGS) by
+  appending them to the internally used JUCE_*FLAGS.
+
+     $ make CPPFLAGS="-Wdate-time -D_FORTIFY_SOURCE=2"
+
+- The generated project Makefile will allow verbose builds (showing you the
+  actualy compiler/linker invocation)
+
+      $ make V=1
+
+- The Introjucer *itself* is linked against libjuce, rather than including the
+  modules statically. (Though you will hopefully never notice a difference here)
+
+
+
+# Debian packages that depend on JUCE
+
+This is a quick guideline for packaging upstream software that uses JUCE for
+Debian.
+
+- Build-Depend on 'libjuce-dev'.
+
+- Patch the project's (generated) Linux/Makefile:
+  - Remove all references to the juce-modules from OBJECTS.
+    AFAICT, these are the lines starting with "$(OBJDIR)/juce_".
+  - For "Release" builds:
+    - Add "$(shell pkg-config --cflags juce)" to the projects CFLAGS
+    - Add "$(shell pkg-config --libs juce)" to the projects LDFLAGS
+      (as a bonus, you can now remove *most* explicitly mentioned libraries,
+       e.g. "-lX11")
+  - For "Debug" builds use 'juce-dbg' instead of 'juce', but you probably don't
+    want Debug builds anyhow...
+
+
+### Notes on *FLAGS
+you are probably aware that JUCE Makefiles override your
+CPPFLAGS/CFLAGS/CXXFLAGS/LDFLAGS, making it hard to apply hardening flags.
+I usually prefix these flags with JUCE_ (e.g. "CPPFLAGS" becomes
+"JUCE_CPPFLAGS") and then append the external flag ("$(CPPFLAGS)") to these.
+
+You could recreate the Makefiles by running the project's .jucer file through
+Debian's "Introjucer" (the so-generated Makefiles allow both overriding of
+*FLAGS and building verbosely), but adding 'juce-utils' to the Build-Depends is
+probably an overkill.
+