[libchamplain.wiki] Copy possibly useful stuff from https://wiki.gnome.org/Projects/libchamplain/contributor. To be impr

[Jiří Techet <jiritechet src gnome org>]

commit 9f92724da44fb9e71eb8fcea98379d9952c2acd6
Author: Jiří Techet <techet gmail com>
Date:   Fri Feb 8 17:02:32 2019 +0000

    Copy possibly useful stuff from https://wiki.gnome.org/Projects/libchamplain/contributor. To be improved

 Tips-for-libchamplain-Contributors.md | 90 +++++++++++++++++++++++++++++++++++
 1 file changed, 90 insertions(+)
---
diff --git a/Tips-for-libchamplain-Contributors.md b/Tips-for-libchamplain-Contributors.md
new file mode 100644
index 0000000..87d28ca
--- /dev/null
+++ b/Tips-for-libchamplain-Contributors.md
@@ -0,0 +1,90 @@
+# Coding style
+libchamplain is written using [Telepathy coding 
style](https://telepathy.freedesktop.org/resources/coding_style/). It is close to GNU coding style.
+
+# Fixing memory leaks and debugging
+libchamplain can be affected by memory leaks because it's written in C and memory needs to be managed 
manually. This will have a big impact on any application and on the different bindings. Luckily tools are 
available can provide us with great help.
+
+In order to see where (in which file, line and function) a bug or leak is happening libchamplain and your 
program must first be compiled with debugging symbols. This can be done easily with by overwriting the 
environment variable `CFLAGS`:
+```
+CFLAGS="-O0 -g3" ./configure && make && sudo make install
+```
+
+## Valgrind
+Valgrind has a builtin memory check that can detect most memory leaks. Failing to manipulate libchamplain's 
data structures properly can have disastrous consequences. This happens mostly when a pointer is freed twice, 
not initialized, dereferenced when `NULL` or when memory is written out of bounds. In such cases valgrind can 
help to detect this bugs.
+
+To use valgrind simply run any executable with the following command:
+```
+valgrind --tool=memcheck --leak-check=full --show-reachable=yes --trace-children=yes --log-file=leaks.txt 
./launcher-gtk
+```
+
+The output will be saved in the file `leaks.txt`.
+
+If the program is using different memory allocators then setting the environment variables G_SLICE and 
G_DEBUG can help when finding leaks.
+```
+G_SLICE=always-malloc G_DEBUG=gc-friendly valgrind --tool=memcheck --leak-check=full --show-reachable=yes 
--trace-children=yes --log-file=leaks.txt ./launcher-gtk
+```
+
+### Valgrind error suppression
+Valgrind will produce a lot of information as other libraries (glib, gtk2 and clutter) or even OpenGL 
drivers (fglrx is quite terrible with valgrind) could have some "leaks". These are not always real leaks but 
global initialization of variables that are never reclaimed at the the end of the program because most 
libraries don't provide a cleanup function as the OS takes care of this. Nevertheless this is very annoying 
as the output becomes too verbose.
+
+Luckily valgrind can be instructed to ignore error by providing a suppressions file. To generate a 
suppression file all that's needed is to execute a program through valgrind and to clean up the output file, 
then that file can be reused for all programs. A good way to generate the suppression file is to use one of 
the demos and to execute it.
+
+```
+valgrind --tool=memcheck --leak-check=full --show-reachable=yes --trace-children=yes --gen-suppressions=all 
demos/.libs/launcher-gtk 2> champlain.sup
+```
+
+Once the suppressions file is generated it should be cleaned of all comments added by valgrind:
+```
+perl -i -pe 's/^=.*\n$//' champlain.sup
+```
+
+Then the suppression file can be used with any program by doing:
+```
+valgrind --tool=memcheck --leak-check=full --show-reachable=yes --trace-children=yes 
--suppressions=champlain.sup demos/.libs/launcher-gtk
+```
+
+**NOTE**: Before using the suppressions file you should filter out all champlain related errors as these are 
the ones that need to be addressed.
+
+## GDB
+Sometimes a program will crash without giving too much information, in such situations it will be preferable 
to run the program through a debugger. To run a program through the debugger do:
+```
+gdb --args PROGRAM ARGS
+```
+
+Take note that the demo programs in the folder demo are not real program but shell scripts. Thus in order to 
debug a demo you have to use the real executable which can be found in the folder `.libs`. For instance to 
debug the demo `launcher-gtk` simply do:
+```
+libtool --mode=execute gdb --args demos/launcher-gtk
+```
+
+Other times the program will run but emit warnings to the console. While the warning may be clear it will 
most likely fail to report the exact location where the error occurred. This can be found by telling glib to 
transform all warnings into fatal errors and by running the program through the debugger. Once the warning 
will be emitted it will cause the program to abort. To debug all glib warnings simply do:
+```
+G_DEBUG=fatal-warnings libtool --mode=execute gdb --args ./launcher-gtk
+```
+
+More information on [How to run and debug your GTK+ 
application](https://developer.gnome.org/gtk3/unstable/gtk-running.html) and [How to run and debug your GLib 
application](https://developer.gnome.org/glib/stable/glib-running.html).
+
+## Clang Static Analyzer
+Even though no static analysis tool can find all problems in your source code, it can help you find bugs 
that you would not notice otherwise. Clang (LLVM's C language frontend) contains such a tool.
+
+First, you need to install LLVM and clang - under Ubuntu this means installing packages of the same names; 
alternatively, you can compile them from the tarballs. Under Ubuntu 10.4 there appears to be some packaging 
problem, so you have to create a symlink to the analyzer:
+```
+sudo ln -s /usr/bin/ccc-analyzer /usr/bin/c++-analyzer
+```
+
+To get the report, go to the libchamplain root directory and run:
+```
+scan-build ./configure
+```
+
+(with whatever configure options you want to use), and
+```
+scan-build make
+```
+
+(if you have multicore CPU, use the `-j` option to speed up the analysis). If there are any problems 
detected, the scanner creates a directory of the form `scan-build-YYYY-MM-DD-N` under `/tmp`. To see the 
results, just open `index.html` with your web browser inside this directory and see the problems.
+
+Clang can be used also as an alternative compiler for libchamplain. Run
+```
+./configure CC=clang
+```
+to use it for compilation.
\ No newline at end of file