contrib: add a HOWTO for new users

[libam7xxx.git] / HACKING.asciidoc

diff --git a/HACKING.asciidoc b/HACKING.asciidoc
index ed2a46b..bf8cc28 100644 (file)
--- a/HACKING.asciidoc
+++ b/HACKING.asciidoc
@@ -5,6 +5,35 @@
 libam7xxx uses the linux kernel coding style:
 http://kernel.org/doc/Documentation/CodingStyle
 
 libam7xxx uses the linux kernel coding style:
 http://kernel.org/doc/Documentation/CodingStyle
 

+=== Getting and compiling libam7xxx
+
+libam7xxx depends on 'libusb-1.0' and optionally on 'libav' or 'ffmpeg' for
+its example programs, the build system used is 'cmake'.
+
+On a Debian based system, the dependencies can be installed with this command:
+
+  $ sudo aptitude install cmake \
+                          libusb-1.0-0-dev \
+                          libavformat-dev \
+                          libavcodec-dev \
+                          libavdevice-dev \
+                          libswscale-dev \
+                          libxcb1-dev
+
+With libav/ffmpeg version previous than 0.9 this patch is needed:
+http://git.ao2.it/libam7xxx.git/blob_plain/refs/heads/debian:/debian/patches/0001-Revert-am7xxx-play-switch-to-avcodec_encode_video2.patch
+
+The library and the example programs can be compiled following these steps:
+
+  $ git clone git://git.ao2.it/libam7xxx.git
+  $ cd libam7xxx
+  $ mkdir build
+  $ cd build
+  $ cmake ../
+  $ make
+
+After that the example programs can be found in the +bin/+ subdirectory.
+

 === Debug builds
 
 The suggested way to hack on the project is:
 === Debug builds
 
 The suggested way to hack on the project is:


@@ -22,6 +51,13 @@ can run:
   $ cmake -D CMAKE_C_COMPILER=cgcc ../
   $ make
 
   $ cmake -D CMAKE_C_COMPILER=cgcc ../
   $ make
 

+And for a pre-release check with a different compiler, which never hurts:
+
+  $ mkdir build
+  $ cd build
+  $ cmake -D CMAKE_C_COMPILER=clang -D CMAKE_BUILD_TYPE=debug -D STRICT_COMPILATION_CHECKS=ON ../
+  $ make
+

 === Cross Builds
 
 If you want to build for MS Windows:
 === Cross Builds
 
 If you want to build for MS Windows:


@@ -29,15 +65,17 @@ If you want to build for MS Windows:
   $ sudo aptitude install mingw-w64
   $ mkdir build
   $ cd build
   $ sudo aptitude install mingw-w64
   $ mkdir build
   $ cd build

-  $ wget -nv http://sourceforge.net/projects/libusbx/files/releases/1.0.11/Windows/libusbx-1.0.11-win.7z
-  $ 7z -olibusbx-1.0.11-win x libusbx-1.0.11-win.7z
+  $ wget -nv http://download.sourceforge.net/project/libusb/libusb-1.0/libusb-1.0.18/libusb-1.0.18-win.7z
+  $ 7z -olibusb-1.0.18-win x libusb-1.0.18-win.7z
+  $ wget -nv http://win32.libav.org/releases/libav-10.1-win32.7z
+  $ 7z -olibav-10.1-win32 x libav-10.1-win32.7z

   $ cmake  \
           -D GNU_HOST=i686-w64-mingw32 \
           -D CMAKE_TOOLCHAIN_FILE=../cmake_modules/mingw_cross_toolchain.cmake \
           -D CMAKE_INSTALL_PREFIX=libam7xxx-win/ \
   $ cmake  \
           -D GNU_HOST=i686-w64-mingw32 \
           -D CMAKE_TOOLCHAIN_FILE=../cmake_modules/mingw_cross_toolchain.cmake \
           -D CMAKE_INSTALL_PREFIX=libam7xxx-win/ \

-          -D LIBUSB_1_INCLUDE_DIR=libusbx-1.0.11-win/include/libusbx-1.0 \
-          -D LIBUSB_1_LIBRARY=libusbx-1.0.11-win/MinGW32/dll/libusb-1.0.dll \
-          -D BUILD_AM7XXX-PLAY:BOOL=FALSE \
+          -D LIBUSB_1_INCLUDE_DIR=libusb-1.0.18-win/include/libusb-1.0 \
+          -D LIBUSB_1_LIBRARY=libusb-1.0.18-win/MinGW32/dll/libusb-1.0.dll \
+          -D FFMPEG_ROOT=$(pwd)/libav-10.1-win32/win32/usr \

           ../
   $ make
 
           ../
   $ make
 


@@ -51,3 +89,8 @@ dynamic analyzer by using a command like:
 
   $ valgrind --leak-check=full --show-reachable=yes --track-origins=yes \
     ./bin/picoproj -W 800 -H 480 -f my_image.jpg
 
   $ valgrind --leak-check=full --show-reachable=yes --track-origins=yes \
     ./bin/picoproj -W 800 -H 480 -f my_image.jpg

+
+or, for am7xxx-play:
+
+  $ valgrind --leak-check=full --show-reachable=yes --track-origins=yes \
+    ./bin/am7xxx-play -f x11grab -i :0