Added compatibility and portability sections.

git-svn-id: https://svn.code.sf.net/p/gphoto/code/trunk/libgphoto2@3890 67ed7778-7388-44ab-90cf-0a291f65f57c

1 files changed, 152 insertions, 1 deletions

diff --git a/HACKING b/HACKING
index 60ececce8..82b3cd188 100644
--- a/HACKING
+++ b/HACKING
@@ -22,7 +22,7 @@ checkout -P
 in $HOME/.cvsrc and send us the output of "cvs diff some_file.c".
 
 We prefer patches against the current CVS version very much over
-patches agains old released versions, but these are also welcome :-)
+patches against old released versions, but these are also welcome :-)
 
 source files
 ------------
@@ -145,6 +145,157 @@ following stuff into their .emacs file:
 
 -----8<------------------------------------------------
 
+compatibility
+-------------
+
+One gphoto2 has been officially launched as a 2.0 version, it is important
+that the API does not change frequently.  It is annoying to users when they
+have to upgrade all sort of libraries and applications just to get an
+upgraded camera driver.  Once the 2.0 release has been made, try to
+follow these guidelines:
+
+    - New versions of the gphoto2 core libraries in the 2.0 series shall
+    work with all older 2.0 camera libraries
+
+    - New versions of the gphoto2 camera libraries in the 2.0 series shall
+    work with all older 2.0 core libraries (this one may be relaxed)
+
+    - Before fixing 2.0 in stone, look for weaknesses in the current
+    APIs that may preclude enhancements in the future.  For instance, there
+    should be some filler entries added to the end of struct _CameraFunctions
+    so that a newer camera library that tries to fill in an entry that
+    is added in gphoto2 ver. 2.1 that doesn't exist there now won't
+    overwrite something important.
+
+    - Try to work using the existing API instead of making minor
+    changes here and there; think about whether the change you're proposing
+    will demonstratively benefit gphoto2 or it's just a "nice to have"
+
+    - Instead of adding a new parameter to a function, create a new function
+    that enhances the other one (where appropriate)
+
+    - If a new parameter is absolutely needed in an existing function
+    call, rename the function with the new parameter, but leave the
+    existing function as is, calling the new function with a default value
+    for the new parameter
+
+    - When adding entries to a common structure, add them to the end of the
+    struct so that the other members aren't shifted around.  Consider what
+    will happen if that member is not filled in by an older application.
+
+    - Don't delete entries from a common struct; instead, just rename them
+    into filler entries.
+
+    - If there is a very good reason to break compatibility, wait until
+    release 3.0 to make those changes
+
+    - Delay the release of 3.0 until the benefits outweigh the consequences
+    to the user of an incompatible library version.
+
+
+portability
+-----------
+
+Please remember that people will be running gphoto2 on a wide variety
+of operating systems and CPUs and will be compiling it on a wide
+variety of C compilers.  As you write your code, be sure not to make
+any assumptions in your code that aren't in the ANSI C89 standard.
+If your code absolutely needs some feature or header file that isn't
+available everywhere, write an autoconf test so that the configure
+script will detect if that feature is available at compile time and
+provide an alternative for those compilers that don't support it.
+
+There are lots of subtle portability issues that you should keep in
+the back of your mind.  Following are some of the major ones that affect
+gphoto2.  See the paper "Notes on Writing Portable Programs in C" at
+<URL:http://www.literateprogramming.com/portableC.pdf> or "Writing
+Portable C with GNU Autotools" at
+<URL:http://sources.redhat.com/autobook/autobook/autobook_110.html#SEC110>
+for more details.
+
+
+* A char can be signed or unsigned.
+
+Use 'signed char' or 'unsigned char', or int8_t or uint8_t from _stdint.h,
+to be sure to get the type you want when it is important.
+
+
+* A pointer is not necessarily an int.
+
+Don't cast a pointer to an int and vice-versa.
+
+
+* An int can be almost any width.
+
+Don't assume that it's 32 or 16 bits or any other value.  Instead,
+if you need a variable of a certain size, include the gphoto2 header
+file _stdint.h (or gphoto2-endian.h) and use the C99-style fixed-width
+types declared therein.  If you don't really care about the size of a
+variable (e.g. as the index variable in a small for loop), you can still
+use an int as it's often the most efficient type for each processor.
+It's usually the case that a char is 8 bits, int is at least 16 bits,
+and a long is at least 32 bits.  Never assume that int or long (or char,
+for that matter) have a specific size, or that they will overflow at a
+particular point.  Use a size-specific type (e.g. uint32_t) if necessary.
+
+
+* The sequence of bytes received from a camera isn't necessarily the
+same as how those bytes are stored in a C struct in memory.
+
+Many compilers will place padding bytes between the elements of a C
+struct to improve run-time efficiency on the target processor.  This
+means that if you read a camera packet directly into such a struct,
+the bytes will not line up and your program will use the wrong values.
+
+A similar problem occurs even if you read just a couple of bytes
+into an int, if gphoto is running on a processor with a different
+"endianness" than the camera.
+
+The most portable solution is to use the macros available in the
+gphoto2-endian.h header file.  When you read a packet from a camera
+(writing is similar), use a uint8_t array or heap space to store the
+raw packet.  Extract each member of the packet out of the array one at a
+time using a macro like be32atoh from gphoto2-endian.h.  Those macros
+take care of both those problems at once.
+
+The macros have the form AANN[a]toh or htoAANN[a], where AA is `le'
+(little-endian) or `be' (big-endian), NN is 16 or 32 (bits in the
+word) and `a', if present, means that the preceding type is located in
+a byte array, not an integer. `h' refers to `host', and could be big
+or little-endian depending on the current CPU.  Upper-case versions of
+these macros (where appropriate) do the conversion in place.  Do a
+'man ntohl' to find out more about why these are needed, and the generated
+gphoto2-endian.h file for more descriptions.
+
+
+* Your code won't necessarily be compiled with gcc.
+
+gcc is a great C compiler, but it isn't installed on everybody's
+systems (yet!).  Avoid use of proprietary gcc language extensions and
+features that aren't available in ANSI C89 compilers.  Sure, there's
+probably some code that would be more elegant using a gcc language
+extension, but somebody, somewhere will be denied the use of the best
+digital camera application in existence because of it.
+
+This also applies to new standard C features that appeared in the
+C99 specification of the language.  There is not much support yet
+in the installed base of C compilers to allow unrestricted use, but
+this will change as time goes by.  In the meantime, use autoconf to
+detect if the feature is available at run-time and act appropriately
+(for an extreme example, see how configure handles the C99 header
+file <stdint.h> or inline keyword).
+
+Although one-line comments starting with // have been available
+in most compilers for several years, they were only officially
+added to the ANSI C99 spec and some compilers out there still
+don't support them.  The "inline" keyword also falls into the same
+category, but configure tests for this feature at compile time
+and supplies the appropriate inline keyword as a macro.  Finally,
+don't add compiler-specific flags to make files directly, as many
+of them are specific to one compiler and will cause the build to
+fail when using another.
+
+
 Local Variables:
 mode:text
 End: