diff --git a/ChangeLog b/ChangeLog index 10f27cf64..365bdb7b5 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2012-02-04 Alexandre Duret-Lutz + + * HACKING: Minor updates and corrections. + 2012-02-15 Alexandre Duret-Lutz Fix a race condition on the CGI script. diff --git a/HACKING b/HACKING index 4c6e14b14..34d0ff7ba 100644 --- a/HACKING +++ b/HACKING @@ -13,7 +13,7 @@ since the generated files they produce are distributed.) GNU Autoconf >= 2.61 GNU Automake >= 1.11 - GNU Libtool >= 2.2 + GNU Libtool >= 2.4 GNU Flex (the version seems to matters, we used 2.5.35) GNU Bison >= 2.4.2 SWIG >= 1.3.31 @@ -54,14 +54,14 @@ documentation has just been built. Debugging Libtool executables ----------------------------- -The executable generated in the various testsuite directories of Spot, +The executables generated in the various testsuite directories of Spot are not real binaries. Because we use libtool to compile the spot -library in a portable manner, these executable are just script that -run the actual binary after setting some environment variable so that +library in a portable manner, these executables are just scripts that +run the actual binary after setting some environment variables so that the OS can find the library in the build tree. -A consequence is that tools like gdb or valgrind, that expect to -work on a binary, will be confused by the script. Example: +A consequence is that tools like gdb or valgrind, that expect to work +on a binary, will be confused by the script. Example: % cd src/tgbatest % file ltl2tgba @@ -70,8 +70,8 @@ work on a binary, will be confused by the script. Example: "/home/adl/git/spot/src/tgbatest/ltl2tgba": not in executable format: File format not recognized (gdb) quit -The proper way to work on these libtool scripts is via the libtool -command: +The proper way to run any command on these fake binaries is via +libtool: % ../../libtool --mode=execute file ltl2tgba /home/adl/git/spot/src/tgbatest/.libs/lt-ltl2tgba: ELF 32-bit LSB executable, Intel 80386, version 1 (SYSV), dynamically linked (uses shared libs), for GNU/Linux 2.6.18, not stripped @@ -79,17 +79,25 @@ command: Reading symbols from /home/adl/git/spot/src/tgbatest/.libs/lt-ltl2tgba...done. (gdb) quit -If you are building Spot from the GIT repository the libtool script +You can see that libtool turns ltl2tgba into .libs/lt-ltl2tgba, but it +also sets environment variables so that the dependent shared libraries +will be found. + +If you are building Spot from the GIT repository, the libtool script generated the root of the build tree should be the same as the libtool script that is installed on your system. So you can simply run libtool instead of ../../libtool. -You might also find conveniant to define a alias, a function, or a -script to shorten the invocation of "libtool --mode=execute". - -Also there is an undocumented feature of libtool that allows you to +There is an undocumented feature of libtool that allows you to shorthand "libtool --mode=execute" as "libtool execute" or even -"libtool e". +"libtool e". But you might also find convenient to define an alias, a +function, or a script to make that invocation even shorter. +For instance: + + alias le='libtool --mode=execute ' + +(The trailing space makes it possible to follow this command by +another aliased command.) Profiling with callgrind @@ -154,7 +162,7 @@ Here are example options to pass to configure: CFLAGS='-flto' CXXFLAGS='-flto' LDFLAGS='-fuse-linker-plugin' \ --disable-shared --enable-static -Using --disable-debug prevents the '-g' flag to be passed to the +Using --disable-debug prevents the -g flag to be passed to the compiler, which seems to help avoiding some internal compiler errors. Some binaries (like ltl2tgba) currently fail to compile (internal @@ -173,6 +181,15 @@ conventions are derived from the GNU Coding Standards that we do not put a space before the opening parenthesis in function calls (this is hardly readable when chaining method calls). + +Encoding +-------- + + * Use UTF-8 for non-ASCII characters. + + * If you edit files encoded in Latin-1 (the original default + encoding for the project), feel free to convert them to UTF-8. + Comments -------- @@ -248,7 +265,7 @@ Formating * No space before parentheses in function calls. (`some()->foo()->bar()' is far more readable than - `some ()->foo ()->bar ()' is) + `some ()->foo ()->bar ()') * No space after opening or before closing parentheses, however put a space after commas (as in english). @@ -288,6 +305,15 @@ Formating * No line should be larger than 80 columns. If a line takes more than 80 columns, split it or rethink it. + This makes it easier to print the code, allow people to work on + small screens, makes it possible to display two files (or an + editor and a terminal) side-by-side, ... + + This also puts some pressure on the programmer who writes code + that has too much nested blocks: if you find yourself having to + code between columns 60 and 80 because of identation, consider + writing helper functions to simplify the structure of your code. + * Labels or case statements are back-indented by two spaces, without space before the `:'. @@ -321,14 +347,13 @@ Formating int* q; instead of int *p, *q; - The former declarations also allow you to describe each variable. + The former declarations also allow you to comment each variable. * The include guard for src/somedir/foo.hh is SPOT_SOMEDIR_FOO_HH - Naming -====== +------ * Functions, methods, types, classes, etc. are named with lowercase letters, using an underscore to separate words. @@ -367,11 +392,11 @@ Naming * C Macros are all uppercase. - * Use *.hxx for the implementation of templates that are private - to Spot (i.e. not installed) and need to be included multiple times. + * Use *.hxx for the implementation of templates that are private to + Spot (i.e., not installed) and need to be included multiple times. Other style recommandations -=========================== +--------------------------- * Do not use the NULL macro, it is not always implemented in a way which is compatible with all pointer types. Always use 0 instead. @@ -392,3 +417,6 @@ Other style recommandations otherwise is to declare two classes with the same name: the linker will ignore one of the two silently. The resulting bugs are often difficult to understand.) + + * Always code as if the person who ends up maintaining your code is + a violent psychopath who knows where you live.