Whilst working on an application that makes use of a 1394a/firewire camera I found a strange bug/feature with libdc1394. The problem was dc1394 was being used to the mode of the camera to 800×600 resolution. However, when querying the frame size after dequeuing the frame, the size was only 640×480. Ie: See the below snippits:

..
dc1394error_t result = dc1394_video_set_mode( this->camera, DC1394_VIDEO_MODE_800x600_RGB8);
if( result != DC1394_SUCCESS )
exit(0);
 
....
dc1394video_frame_t *frame=NULL;
dc1394error_t result;
 
// capture one frame
result = dc1394_capture_dequeue( this->camera, DC1394_CAPTURE_POLICY_WAIT, &frame );
if( result != DC1394_SUCCESS )
exit(0);
 
// Allocate image memory if required
if( this->lastFrame.image == NULL ){
memcpy(this->lastFrame,frame, sizeof(dc1394video_frame_t));
this->lastFrame.image = (uint8_t *)malloc(frame->total_bytes * sizeof(uint8_t));
 
..

At this point total_bytes was 921600 which works out to be 640x480x3 (RGB);

I was stumped. I asked for one mode and got another back. All with no errors what so ever from libdc1394.

After over an hour of debugging, google searching and more,  I eventually found the reason.  The comment that ended up in the code explains the cause:

// Shutdown any isotransports that are setup for the camera.
// It turns out that libDC1394 will quite happily let you set modes,
// framerates, etc but if there is an iso stream running none of them
// will actually take affect. Hence you can set a 800x600 res and get
// back 640x480 video frame - really nice libdc1394. It could at least
// indicate there was a active stream when setting the mode!
// Anyway to deal with this we force the camera to stop capturing
// before we change the settings, if the camera was capturing prior to
// setConfiguration being called, we restart the capture

So the solution is to make sure the iso transmission stream has been shutdown. this can be achieved using:

dc1394_video_set_transmission( this->camera, DC1394_OFF );
dc1394_capture_stop( this->camera );

An easy fix but certainly an annoying setup. I’ve not tested it but I’m guessing many of the other functions:

• dc1394_video_set_framerate
• dc1394_video_set_iso_speed
• dc1394_feature_set_mode
• dc1394_video_set_one_shot

are also affected.

Recently I was working on a piece of code that updated a texture with a camera frame. The application was using the fixed function (non shaders) pipeline of OpenGL. Whilst I didn’t notice it at first, I soon found that the camera image was very delayed. For example the camera was capturing at 30 frames per second, but the screen update rate was only 6 frames per second.

After commenting out vast amounts of code, disabling functions the reason behind the slow frame rates was traced to the OpenGL call: glTexSubImage2D. The exact call that was being made was:

glTexSubImage2D(GL_TEXTURE_2D, 0, 0, 0,  mWidth, mHeight,  GL_RGB, GL_UNSIGNED_BYTE, image->getData());

Everything to this call looked normal. I tried a simple test program that used glTextSubImage2D and surprizingly it ran fast! So at this point I was a little confused. How could two very similar programs produce different results.
I kept searching. I tried Google searches found various comments but none of them seemed to work.

Eventually I looked at the Texture class I had been using and began commenting lines out of that. It was only when I found and commented out the line:

glTexParameteri(GL_TEXTURE_2D, GL_GENERATE_MIPMAP, GL_TRUE );

Things improved. This makes perfect sense as well. Generating a mipmap each frame is expensive. A quick fix and the application was running smoothly!

XI2 is the first major rewrite of the XInput specification in years and with it comes a lot of enhanced functionality, but also a new API. The API was deliberately designed not to be backward compatible. Why? To prevent both XI1 and XI2 features to be intermingled. XI2 brings with it a new device model and a new input model. Both of these are incompatible with XI1. The decision to break the API was not a light one by Peter Hutterer, the main XI2 developer. Supporting XI1 would have ment future changes to XI2 would be impossible – there’s only so far you can push an out dated protocol and api. The added complexity of trying to maintain 2 code paths was also determined to be too high. XI2 is more than just a api/abi change. It literally change the entire input subsystem of the Xorg Xserver. XI2 supports:

• Mulitple Independent Master Devices (MPX)
• Subpixel Accuracy for input devices
• Support for 32bit key codes
• .. lots more See: http://fedoraproject.org/wiki/Features/XI2 for full details

With that in mind, the new XI2 API often leaves someone who’s been working with the XI1 wondering what the equivilant XI2 API call is. Most functions have an equivilant in XI2 function though the usage has more often than not, changed dramatically. Below is some examples of how to convert XI1 code to XI2 compatible code and a list of some of the changes which have occurred. If you find something missing, please add to the comments.

Change Overview

The biggest change that any XI1 developer will notice is the XDevice * type has vanished. All XI2 devices make use of the XID type instead. Under the hoods, in the Xserver and XDevice really equates back to an XID anyway now. The next biggest change XI1 developers will notice is the entire XInput2 API has had shifted namespaces. All XInput2 functions, types, etc are now prefixed with XI (ie XIEventMask). This was designed to force segregation of XI1 -> XI2 code.

The header file you include has also changed. Instead of:

#include <X11/extensions/XInput.h>

It’s now:

#include <X11/extensions/XInput2.h>

Notable Changes

• Proximity events are no longer supported, these are now reported as regular events on another axis (ie think of a pressure axis)
• Events are longer use device classes, instead all events are type XIEvent (a type of XEvent). Hence there is no need to pass around an array of integer classes anymore when registering for events, instead a single XIEventMask will do what is needed. The macros XISetMask and XIGetMask help with using the mask.

There’s also been a lot of changes to structures, functions, types and how they are used.

Event Changes

Structure/Type Changes

XIEventMask mask;
mask.deviceid=//some device or XIAllDevices for all devices<
mask.mask_len=2;
mask.mask=calloc(mask.mask_len, sizeof(char));
XISetMask(mask.mask, XI_ButtonPress);
..
XISelectEvents(display, win, &mask, 1)

Function/Macro Changes

Examples

Below are some examples of how to use some of the new XI2 functions.

Event Processing – Registering For Events

A simple indication how to register for events (XI2 greatly simplifies this)

• XInput 1 (Taken from: http://cgit.freedesktop.org/xorg/app/xinput/tree/src/test.c)

static int           motion_type = INVALID_EVENT_TYPE;
static int           button_press_type = INVALID_EVENT_TYPE;
static int           button_release_type = INVALID_EVENT_TYPE;
static int           key_press_type = INVALID_EVENT_TYPE;
static int           key_release_type = INVALID_EVENT_TYPE;
static int           proximity_in_type = INVALID_EVENT_TYPE;
static int           proximity_out_type = INVALID_EVENT_TYPE;
 
static int register_event(Display *dpy, XDeviceInfo *info)
{
    XEventClass         event_list[7];
    int                 i;
    XDevice             *device;
    XInputClassInfo     *ip;
 
    device = XOpenDevice(dpy, info->id);
 
    // Check for open error
    if (device->num_classes > 0) {
        for (ip = device->classes, i=0; i<info->num_classes; ip++, i++) {
            switch (ip->input_class) {
            case ButtonClass:
                DeviceButtonPress(device, button_press_type, event_list[number]); number++;
                DeviceButtonRelease(device, button_release_type, event_list[number]); number++;
                break;
 
            case ValuatorClass:
                DeviceMotionNotify(device, motion_type, event_list[number]); number++;
                if (handle_proximity) {
                    ProximityIn(device, proximity_in_type, event_list[number]); number++;
                    ProximityOut(device, proximity_out_type, event_list[number]); number++;
                }
                break;
 
            default:
                fprintf(stderr, "unknown class\n");
                break;
            }
      }
 
   if (XSelectExtensionEvent(dpy, root_win, event_list, number)) {
            fprintf(stderr, "error selecting extended events\n");
            return 0;
        }
   }

• XInput 2:
  (Taken from: http://who-t.blogspot.com/2009/05/xi2-recipes-part-1.html)
  

XIEventMask eventmask;
unsigned char mask[1] = { 0 }; /* the actual mask */
 
eventmask.deviceid = 2;
eventmask.mask_len = sizeof(mask); /* always in bytes */
eventmask.mask = mask;
/* now set the mask */
XISetMask(mask, XI_ButtonPress);
XISetMask(mask, XI_Motion);
XISetMask(mask, XI_KeyPress);
 
/* select on the window */
XISelectEvents(display, window, &eventmask, 1);

Event Processing – Listening/Processing Events

A simple indication how to get events from XI1 and XI2

• XInput 1:

  //setup via other means
  int motion_type, button_press_type,button_release_type;
   
  void doEvents(Display    *dpy)
  {
   
   XEvent        Event;
   
      while(1) {
          XNextEvent(dpy, &Event);
          if (Event.type == motion_type) {
              XDeviceMotionEvent *motion = (XDeviceMotionEvent *) &Event;
              ...
   
          } else if ((Event.type == button_press_type) ||
                     (Event.type == button_release_type)) {
                        XDeviceButtonEvent *button = (XDeviceButtonEvent *) &Event;
   
              ...
          }else if ((Event.type= .... )){
              ...
       }
  }

• XInput 2

  //Somewhere else...
   
  int xi_opcode;
  if (!XQueryExtension(display, "XInputExtension",&xi_opcode,&event, &error)) {
  printf("X Input extension not available.\n");
  return EXIT_FAILURE;
  }

  void doEvents (Display *dpy )
  {
      while(1) {
          XEvent        ev;
          XGenericEventCookie *cookie = &ev.xcookie;
          XNextEvent(dpy, &ev);
   
          if (XGetEventData(dpy, cookie) && cookie->type == GenericEvent
              && cookie->extension==xi_opcode)
          {
              XIDeviceEvent *event = cookie->data;
   
              printf("EVENT type %d\n", event->evtype);
              switch (event->evtype)
              {
                  //
                  // In all below event>deviceid contains the id of the device
                  //
                  case XI_DeviceChanged:
                      XIDeviceChangedEvent *dc = cookie->data;
                      ...
                      break;
                  case XI_HierarchyChanged:
                      XIHierarchyEvent *he = cookie->data;
                      ...
                      break;
                  case XI_RawEvent:
                      XIRawEvent *re = cookie->data;
                      ...
                      break;
                  case XI_FocusIn:
                  case XI_Enter:
                      XIEnterEvent *ee = cookie->data;
                      ...
                      break;
                  case XI_FocusOut:
                  case XI_Leave:
                      XILeaveEvent *le = cookie->data;
                      ...
                      break;
                  case XI_PropertyEvent:
                      XIPropertyEvent *pe = cookie->data;
                      ...
                      break;
                  case XI_Motion:
                  case XI_ButtonPress:
                  case XI_ButtonRelease:
                  case XI_KeyPress:
                  case XI_KeyRelease:
                      // do something with event (XIDeviceEvent contains data)
                      break;
              }
          }
       }
    }

Sadly this kept breaking in xorg/lib/libX11 with the error:

xcb_io.c: In function 'require_socket':
xcb_io.c:35: warning: implicit declaration of function 'xcb_take_socket'
xcb_io.c:35: warning: nested extern declaration of 'xcb_take_socket'
xcb_io.c: In function 'process_responses':
xcb_io.c:188: error: 'GenericEvent' undeclared (first use in this function)
xcb_io.c:188: error: (Each undeclared identifier is reported only once
xcb_io.c:188: error: for each function it appears in.)
xcb_io.c:189: error: 'xcb_ge_event_t' undeclared (first use in this function)
xcb_io.c:189: error: expected expression before ')' token
xcb_io.c:193: error: expected expression before ')' token
xcb_io.c: In function '_XSend':
xcb_io.c:332: warning: implicit declaration of function 'xcb_writev'
xcb_io.c:332: warning: nested extern declaration of 'xcb_writev'

For the life of me I couldn’t make sense of it. GenericEvent is defined in xcb/xcb.h and checking the preprocessor output xcb.h was being included. Likewise the lack of xcb_ge_event_t was baffling me as it was certain in xcb/xcb.h. It wasn’t till I looked a little closer that I realised that the wrong xcb.h was being used. Turns out that /usr/local/include/xcb/xcb.h was being used however I wanted /usr/local/MPX/include/xcb/xcb.h to be used. Hence I tried adding -I/usr/local/MPX to CFLAGS with no success and also tried setting CC=”gcc -I/usr/local/MPX” also with no success. It just didn’t make sense!

Looking at the gcc line, /usr/local/MPX should have been used first. It wasn’t until I finally check the preprocessor what it thought the system paths were did it all make sense.

The output from cpp is below:

Using built-in specs.
Target: amd64-undermydesk-freebsd
Configured with: FreeBSD/amd64 system compiler
Thread model: posix
gcc version 4.2.1 20070719  [FreeBSD]
 /usr/libexec/cc1 -E -quiet -v -I. -I../include/X11 -I../include -I../include/X11
-I../include -I../include/X11 -I../src/xcms -I../src/xkb -I../src/xlibi18n -I/usr/local/include 
-D_LONGLONG -DHAVE_CONFIG_H -D_BSD_SOURCE -DHAS_FCHOWN -DHAS_STICKY_DIR_BIT -D_THREAD_SAFE -D_BSD_SOURCE
-DX11_t -DTRANS_CLIENT -isystem /usr/local/MPX/include xcb_io.c -o xcb_io.lo -Wall -Wpointer-arith
-Wstrict-prototypes -Wmissing-prototypes -Wmissing-declarations -Wnested-externs -fno-strict-aliasing -fworking-directory -O0

ignoring duplicate directory "/usr/local/MPX/include"
ignoring duplicate directory "/usr/include"
ignoring duplicate directory "../include/X11"
ignoring duplicate directory "../include"
ignoring duplicate directory "../include/X11"
#include "..." search starts here:
#include <...> search starts here:
 .
 ../include/X11
 ../include
 ../src/xcms
 ../src/xkb
 ../src/xlibi18n
 /usr/local/include
 /usr/local/MPX/include
 /usr/include
End of search list.

It turns out that jhbuild sets the environment variable C_INCLUDE_PATH, in this case to /usr/local/MPX/include. This variable adds a library to the system search path. Whilst it prepends to the system search path,  -I options prepend the system search path, hence with one -I option being /usr/local/include, we get the ordering incorrect and the wrong header is used.  

So now it was up to working out why /usr/local/include was needed. Searching config.log it turns out the bigfontproto was needed by libX11, pkg_config was searching for it and finding it not in /usr/local/MPX/lib/share/pkg_config but in /usr/local/lib/share/pkg_config. The reason for this is bigfontproto wasn’t listed as a dependancy in the xorg.modules file used by jhbuild (avaliable at:http://cgit.freedesktop.org/xorg/util/modular/tree/xorg.modules). Because of this bigfont proto wasn’t being built by jhbuild. Hence the only bigfontproto that existed on the box was the default system bigfont proto which WAS located under /usr/local/include. 

The fix was simple. List xf86bigfontproto as a dependency in xorg.modules and all was good. bigfontproto is now pulled in as a dependency and hence gets built before libX11. pkg_config now correctly finds bigfontproto in /usr/local/MPX/lib/share/pkg_config hence doesn’t need to fallback to the system version so -I/usr/local/include doesn’t get added to the gcc line. Hence the compiler uses /usr/local/MPX/include/xcb/xcb.h rather than the one in /usr/local/include/xcb/xcb.h and the compiler errors vanish.

So now things are building and I’m off for a coffee!
(xorg.modules has also been correctly updated so some other poor person doesn’t have the same issues).

dnlCommon/Logger.cpp: In member function 'void dnlCommon::Logger::setMask(std::ostream&, std::bitset<5ul>)':
dnlCommon/Logger.cpp:64: error: invalid initialization of reference of type 'dnlCommon::Logger::LoggerPair&' from expression of type 'const dnlCommon::Logger::LoggerPair'
/usr/local/lib/gcc-4.0.4/include/c++/bits/stl_algo.h: In function '_OutputIterator std::remove_copy(_InputIterator, _InputIterator, _OutputIterator, const _Tp&) [with _InputIterator = std::_Rb_tree_const_iterator<dnlCommon::Logger::LoggerPair>, _OutputIterator = std::_Rb_tree_const_iterator<dnlCommon::Logger::LoggerPair>, _Tp = dnlCommon::Logger::LoggerPair]':
/usr/local/lib/gcc-4.0.4/include/c++/bits/stl_algo.h:1112:   instantiated from '_ForwardIterator std::remove(_ForwardIterator, _ForwardIterator, const _Tp&) [with _ForwardIterator = std::_Rb_tree_const_iterator<dnlCommon::Logger::LoggerPair>, _Tp = dnlCommon::Logger::LoggerPair]'
dnlCommon/Logger.cpp:54:   instantiated from here
/usr/local/lib/gcc-4.0.4/include/c++/bits/stl_algo.h:1037: error: passing 'const dnlCommon::Logger::LoggerPair' as 'this' argument of 'dnlCommon::Logger::LoggerPair& dnlCommon::Logger::LoggerPair::operator=(const dnlCommon::Logger::LoggerPair&)' discards qualifiers

It turned out that the issue occurred with the assignment operator (operator = ) on the stl::set class. Tracing the problem we found that set<TYPE>::iterator is const rather than non cost. Hence calling stl functions that made use of the iterators but also the assignment operator would fail.

Looking further into the problem I found:

      // _GLIBCXX_RESOLVE_LIB_DEFECTS
      // DR 103. set::iterator is required to be modifiable,
      // but this allows modification of keys.
      typedef typename _Rep_type::const_iterator iterator;
      typedef typename _Rep_type::const_iterator const_iterator;

Hmm, that’s strange. A bit of googling revieled the problem to be an issue with the stl standard. Fixes to gcc/g++ are listed at http://gcc.gnu.org/onlinedocs/libstdc++/ext/howto.html in particular error 103 is listed at http://gcc.gnu.org/onlinedocs/libstdc++/ext/lwg-defects.html#103
So it looks like the bug was ratified by the C++ committee in 1998 and it still isn’t fixed in Visual Studio 2005 (VC++ 8.0) !

vector<sometype>::reverse_iterator myiterator...
..
..
myvector.erase(myiterator).

only to find the code didn’t compile. A little baffled I started to looking into why. It turns out you Can’t’ delete from a reverse iterator directly. So the question is How do you delete from a reverse iterator?.

Not wanting to do a full forward traversal to get to the same point I did some Googling. Eventually I found the page: http://www.ddj.com/dept/cpp/184401406

which explains why you can’t delete from the reverse iterator. More importantly it indicates a way that you can delete from the reverse_iterator. So how?

 void Manager::raiseWindow(WMWindow* wmwindow)
 {
   <strong>vector&lt;WMWindow*&gt;::reverse_iterator it = windows.rbegin();</strong>
   while(it != windows.rend())
   {
     if (*it == wmwindow)
     {
      // why ++it see <a class="external free" title="http://www.ddj.com/dept/cpp/184401406" rel="nofollow" href="http://www.ddj.com/dept/cpp/184401406">http://www.ddj.com/dept/cpp/184401406</a>
      <strong>windows.erase((++it).base());</strong>
      windows.push_back(wmwindow);
      break;
     }
     it++;
   }
 
   wmwindow->raise();
 }

Gives an example of how to do it. However, be aware, doing the above erase, invalidates the iterator so don’t go trying to use it again afterwards! }

Assembly Debugging

Starting Out

When debugging assembly in gdb, it’s useful to learn about TUI mode. TUI mode gives gdb text based windows. This allows you to see both the disassembled coded as well as the ability to issue commands at the same time – a must have for debugging.

To enter into TUI mode use:

CTRL-X CTRL-1

This will create a single window. (To get rid of it use

CTRL-X a

Initially this window will not be in the right layout. (In gdb TUI mode, a layout is like a mode, ie assembler mode, etc).

You can tell gdb to change to assembly mode using:

layout asm

Now you should be able to see your program in a disassembled text window.

• Tip: If you want to see registers as well use: layout regs

Common Tasks

In assembly debugging, theres a few common tasks that you need to these are listed below:

View registers

To view registers you can either use:

info all-registers     |   info reg     |  i r

to view the all/some of the registers. You can use:

 layout reg

to bring up a TUI window with all the registers. This window also shows what changes between instructions when your executing them.

To examine the current value of a register you can use:

 info reg es

You can examine the memory the register points to using the x instruction ie:

 x/x $esp    # View mem in hex
 x/b $esp    # View mem in bin
 x/i $esp    # View instruction at address

You can set a register using:

 set $eip = 0x90   # Set current eip to address 0x90

Memory Addresses

If you recall the early lessons in computing there’s two main memory regions in a program – the code segment and the data segment.

The code segment normally consists of executable instructions and static things like constants and strings. You can view the instructions at a memory address using:

disassemble 0x123123

where 0×123123 is an address in memory. This will show you a number of instructions at that address and onwards till the end of the function ends.

You can examine a memory address using

 x  0x123123

The x command takes a number of different parameters/options. It can output binary, hex, strings, instructions etc. For more help on how to use it try: help x in gdb.
You can also print out the value of an address using:

 p 0x123123

like x the p (or print) command the p command takes a number of options for displaying hex, binary etc.

Altering program execution

Say you’ve been debugging a program in assembly. You’ve setup break points, either to memory or functions. Now you’ve found the instruction you want to change. There’s a number of ways you can change it. Chances are the instruction is some type of compare, (cmp, cmpl, jge, jmp, etc). You could possible make the instruction a no instruction (nop) or modify the register the compare relies on to be something else.

In order to alter the line to be a nop you can do something like:

 set *0xbxxxx = 0x90

In this case the address is 0xbxxxx and the instruction (under x86 arch) is 0×90 (nop). However this could cause an issue if the previous instruction was 2 bytes wide. ie:

1> 0x126c :   incl   0xfffff3dc(%ebp)
2> 0x126d :   testb  %al,%al
3> 0x126f :   jne    0x125c

In the above the instruction at line 1 is a 1 byte instruction. The instruction at line 2 is a two byte instruction. How? Looks at the difference between the addresses:

 0x126d - 0x126c = 1 byte
 0x126f - 0x126d = 2 byte

In x86 arch, 0×90 (nop) is only a 1 byte instruction.

If you wanted to modify line 2, you’ld have to set the al register so the test would succeed.

Managing Signals

You can enable/disable signals using the ‘handle‘ command. ie:

handle SIGALARM stop

The options to handle are:

nostop

GDB should not stop your program when this signal happens. It may still print a message telling you that the signal has come in.

stop

GDB should stop your program when this signal happens. This implies the print keyword as well.

print

GDB should print a message when this signal happens.

noprint

GDB should not mention the occurrence of the signal at all. This implies the nostop keyword as well.

pass

GDB should allow your program to see this signal; your program can handle the signal, or else it may terminate if the signal is fatal and not handled.

nopass

GDB should not allow your program to see this signal. 

And to see what signals are currently set and their default setup use:

info signals 

Helpful External Links

http://insecure.org/stf/mudge_buffer_overflow_tutorial.html

Importing To a NEW Vendor Branch

This directory contains virgin sources of the original distribution files on a “vendor” branch. Do not, under any circumstances, attempt to upgrade the files in this directory via patches and a cvs commit. New versions or official-patch versions must be imported. Please remember to import with “-ko” to prevent CVS from corrupting any vendor RCS Ids.

To upgrade to a newer version of a project, when it is available:

1. Unpack the new version into an empty directory.

[Do not make ANY changes to the files.]

• Remove the any files that don’t apply to this project

• 3. Use the command:

 cvs import -ko -m 'Virgin import of Project v<version>' www/share/contrib/project VENDOR project_<version>

• Follow the instructions printed out in step 3 to resolve any conflicts between local changes and the newer version.

Do not, under any circumstances, deviate from this procedure.

To make local changes to cpio, simply patch and commit to the main branch (aka HEAD). Never make local changes on them VENDOR branch.

All local changes should be submitted back to the maintainer of the project for inclusion in the next vendor release.

Importing to an EXISTING Vendor Branch

This text is taken from: http://www.mewburn.net/luke/papers/3rdparty-and-cvs.html Many thanks to the author as it has saved me lots of grief.

It is rare for third-party software to remain unchanged forever; updates are available (even on a regular basis).

An important part of managing third-party software is upgrading to a newer version in a sane way.

The process to import an updated version of a package is similar to importing the original package. However, because changes in the newer version may conflict with any local changes that you may have made to the product, there are a couple of steps that are different.

In this example, we’ll be upgrading dhcp 2.0b1 from pl18 to pl27.

In the directory containing the extracted source import the new version:

 % cvs import -m 'ISC dhcp 2.0b1pl27' net/dhcp ISC dhcp-2-0-b1-pl27
 U net/dhcp/CHANGES
 C net/dhcp/Makefile.conf
     ...
 U net/dhcp/server/dhcpd.leases.cat5
 1 conflicts created by this import.

Use the following command to help the merge:

 cvs checkout -jISC:yesterday -jISC net/dhcp

As you can see there was a conflict on the import (Makefile.conf; the file with the status character of “C”). This is CVS’s way of indicating that those files have been modified from the previous release of the vendor code. Checkout the updated source, automatically merging in any changes. Whether or not CVS suggests a checkout command, you should use a checkout of the form:

 cvs checkout -j old-release-tag -j new-release-tag module

old-release-tag is the previous release tag, and new-release-tag is the one just imported.

For this example the cvs command is:

 % cvs checkout -j dhcp-2-0-b1-pl18 -j dhcp-2-0-b1-pl27 net/dhcp
 U net/dhcp/CHANGES
 U net/dhcp/Makefile.conf
 RCS file: /src/cvsroot/net/dhcp/Makefile.conf,v
 retrieving revision 1.1.1.1
 retrieving revision 1.1.1.2
 Merging differences between 1.1.1.1 and 1.1.1.2 into Makefile.conf
 	...
 U net/dhcp/server/dhcpd.leases.cat5

The advantages of using checkout -j old-release-tag -j new-release-tag include:

• files added or deleted by the vendor between releases are handled automatically, and
• merges between changes are cleaner.

Remember; always use cvs checkout -j old-release-tag -j new-release-tag when checking out code for the first time after you have updated a vendor release. It saves a lot of time.

Search for and resolve any conflicts. A couple of CVS commands are useful for this. cvs update will show any files modified, added, or removed by the vendor between releases.

 % cvs update
 M Makefile.conf

Note that even though include/site.h was locally modified in the previous release, it does not show up as modified here. This is because it was not actually modified by the vendor between the two vendor releases.

cvs diff will display any changes between the last release and this code; changes either from local updates or from the new release. The diff output will also display our changes to include/site.h.

It is probably more useful to use cvs diff -r VENDOR to display changes between the most recent vendor release and this code:

 % cvs diff -r ISC
 Index: Makefile.conf
 =======================================================
 RCS file: /src/cvsroot/net/dhcp/Makefile.conf,v
 retrieving revision 1.1.1.2
 diff -r1.1.1.2 Makefile.conf
 133a134,141
 > ## RMITCS overrides
 > #BINDIR = /usr/local/sbin
 > #CLIENTBINDIR = /usr/local/sbin
 > #ADMMANDIR = /usr/local/man/cat1m
 > #FFMANDIR = /usr/local/man/cat4
 > #VARRUN = /var/run
 > #VARDB = /var/run/dhcp
 > #SCRIPT=none
 Index: includes/site.h
 =======================================================
 RCS file: /src/cvsroot/net/dhcp/includes/site.h,v
 retrieving revision 1.1.1.1
 retrieving revision 1.2
 diff -r1.1.1.1 -r1.2
 39a40
 > #define _PATH_DHCPD_PID       "/var/run/dhcpd.pid"
 45a47
 > #define _PATH_DHCPD_DB        "/var/run/dhcpd.leases"
 50a53
 > #define _PATH_DHCPD_CONF      "/usr/local/etc/dhcpd.conf"

Peruse the output of the diffs and determine if things look reasonable. In this case I am fairly happy with the changes. Refer to the CVS info documentation [4] node “Conflicts example” for more information on resolving conflicts.

Ignoring files via cvsignore

There are certain file names that frequently occur inside your working copy, but that you don’t want to put under CVS control. Examples are all the object files that you get while you compile your sources. Normally, when you run ‘cvs update’, it prints a line for each file it encounters that it doesn’t know about (see section A.16.2 update output).

CVS has a list of files (or sh(1) file name patterns) that it should ignore while running update, import and release. This list is constructed in the following way.

• The list is initialized to include certain file name patterns: names associated with CVS administration, or with other common source control systems; common names for patch files, object files, archive files, and editor backup files; and other names that are usually artifacts of assorted utilities. Currently, the default list of ignored file name patterns is:

   RCS     SCCS    CVS     CVS.adm
   RCSLOG  cvslog.*
   tags    TAGS
   .make.state     .nse_depinfo
   *~      #*      .#*     ,*      _$*     *$
   *.old   *.bak   *.BAK   *.orig  *.rej   .del-*
   *.a     *.olb   *.o     *.obj   *.so    *.exe
   *.Z     *.elc   *.ln
   core

• The per-repository list in ‘$CVSROOT/CVSROOT/cvsignore’ is appended to the list, if that file exists.
• The per-user list in ‘.cvsignore’ in your home directory is appended to the list, if it exists.
• Any entries in the environment variable $CVSIGNORE are appended to the list.
• Any ‘-I’ options given to CVS is appended.
• As CVS traverses through your directories, the contents of any ‘.cvsignore’ will be appended to the list. The patterns found in ‘.cvsignore’ are only valid for the directory that contains them, not for any sub-directories.

In any of the 5 places listed above, a single exclamation mark (‘!’) clears the ignore list. This can be used if you want to store any file which normally is ignored by CVS.

Specifying ‘-I !’ to cvs import will import everything, which is generally what you want to do if you are importing files from a pristine distribution or any other source which is known to not contain any extraneous files. However, looking at the rules above you will see there is a fly in the ointment; if the distribution contains any ‘.cvsignore’ files, then the patterns from those files will be processed even if ‘-I !’ is specified. The only workaround is to remove the ‘.cvsignore’ files in order to do the import. Because this is awkward, in the future ‘-I !’ might be modified to override ‘.cvsignore’ files in each directory.

Note that the syntax of the ignore files consists of a series of lines, each of which contains a space separated list of filenames. This offers no clean way to specify filenames which contain spaces, but you can use a workaround like ‘foo?bar’ to match a file named ‘foo bar’ (it also matches ‘fooxbar’ and the like). Also note that there is currently no way to specify comments.

Branches / Merging Branches / Trunk Merging

This example was taken from: http://dri.freedesktop.org/wiki/CvsPolicy

How to check out a branch

  cvs co -r <keyword>-<revision>-branch xc

How to make a branch

You have no checked out trees

If you want to use the main trunk as the anchor for your branch:

  cvs rtag -b <keyword>-<revision>-branch
  cvs co -b <keyword>-<revision>-branch

If you want to use some other tag as the anchor for your branch:

  cvs rtag -b -r <tag> <keyword>-<revision>-branch
  cvs co -b <keyword>-<revision>-branch

You have a checked out trunk, and you want to tag it and start using it as a branch

  cd <root-of-your-checked-out-tree>
  cvs tag -b <keyword>-<revision>-branch
  cvs update -r <keyword>-<revision>-branch

This makes the {{{<keyword>-<revision>-branch}}} tag sticky. You can verify this by using {{{cvs status}}}, for example in `XFree39/xc`, do this:

  cvs status Makefile

or

  cvs status -v Makefile

How to merge the trunk into your branch

Before you merge your code into the trunk you should first merge the latest trunk code into your branch. After merged code has been tested on your branch, merging into the trunk should be simple.

• Be sure all the changes on your branch are checked in.
• Tag your branch with a ‘freeze’ tag:

  cvs tag <keyword>-<revision>-<date>-freeze

• Merge from the trunk:

  cvs update -d -j HEAD

• Resolve any conflicts from the merge.
• Recompile and build your branch. Test it.
• Check in your changes from the merge.
• Tag your branch with a merge tag:

  cvs tag <keyword>-<revision>-<date>

How to merge your branch to the main trunk

• Be sure your <keyword>-<revision>-<date>-merge tag (on the branch) is up

to date (i.e., in case you changed some files from between the time you merged the trunk onto the branch until you merged the branch onto the trunk).

You can make the tag with:

  cvs tag <keyword>-<revision>-<date>

• Revert your working tree to the main trunk:

  cvs update -A

(Alternatively, you can just check out a new copy of the main trunk.)

• Merge in the changes from your branch:

  cvs update -j <keyword>-<revision>-branch

• Test your merged tree

• Check in your merged tree to the main branch;

  cvs commit -m 'Merged <keyword>-<revision>'

• Tag your merge so we can find it again:

  cvs tag <keyword>-<revision>-<date>-merge

• Now you can make diffs to send to XFree86

Say you keep hacking on your branch after the merge to test a few extra things and you want to merge again. You get the main trunk checked out, as in step 1, then you merge only those changes between your last merge and the most recent revision in your branch:

  cvs update -j <keyword>-<revision>-<date> \
             -j <keyword>-<revision>-branch

aclocal^[1], autoconf^[2], automake^[3], autoheader^[4], and to some extent libtool^[5]

These tools all work together to aid in building applications, libraries and providing a consistent framework for doing so. The problem however, is the tools are hard to use, poorly documented and the learning curve to getting things done is extremely high. Added to this, the tutorials on the web show only the basics of using the system and leave all the useful stuff to the user. The problem is the useful stuff is hard to work out.

Hence this page is not about showing you yet another hello world autotools setup. Instead it give you tips on how to use the autotools and what you can put in those highly cryptic config files: configure.ac, Makefile.am,config.in.

configure.ac/configure.in Tips

This page lists common things that one often needs to do with autoconf. These can be placed either in theconfigure.ac file or if the project is old enough configure.in

Checking Which Operating System The User is Using

This check test to see if the build is for Linux, BSD, Mac, etc. This allows you to tune specific options depending on the platform. This test goes in the configure.ac or configure.in file (depending on what your using).

#
# Platform specific setup
#
#############################
AC_CANONICAL_HOST
# Check for which host we are on and setup a few things
# specifically based on the host
case $host_os in
  darwin* )
        # Do something specific for mac
        ;;
  linux*)
        # Do something specific for linux
        ;;
   *BSD*)
        # Do something specific for BSD
        ;;
    *)
        #Default Case
        AC_MSG_ERROR([Your platform is not currently supported])
        ;;
esac

Setting CFlags/CXXFlags/LDFlags/LIBS

In configure.ac setting ‘CFLAGS and similar variables can be done quite easily. You simply set the variable. However, make sure if your aiming to support multiple platforms you do it in a way that is supported. For instance/bin/sh – the true borne shell doesn’t understands the += variable syntax. Hence something like:

 CFLAGS+=" something"

will fail. You might say that everyone uses bash but things like MacOSX doesn’t. Instead use the syntax:

 CFLAGS="$CFLAGS something"

It’ll work on any platform.

Passing A Variable from configure.ac to Makefile.am

One of the first things that I found myself needing to do was pass the content of a variable from configure.ac toMakefile.am. Whilst this is burried in the autoconf documentation, here’s the 2 second version.

In configure.ac do something like:

 GL_LIBS="-lGLU -lGL"
 AC_SUBST(GL_LIBS)

Then in Makefile.am put:

myapplication_bin_LDADD=@GL_LIBS@
The AC_SUBST tells autoconfig that a substitution should happen when building the Makefile (s). HenceGL_LIBS is expanded correctly. Of course, you probably want to do a much better check for your libs :)

Defining a #defining for use in C/C++ code

In configure.ac

 AC_DEFINE([MYDEFINE],[SOMEVALUE],[Description: Make #define MYDEFINE SOMEVALUE])

in config.h.in

 #undef MYDEFINE

Checking for C++ headers/C++ Libraries, not pkg-config supported

AC_LANG_PUSH([C++])
AC_CHECK_HEADERS([boost/foreach.hpp])
AC_CHECK_LIBS([boost])
AC_LANG_POP([C++])

Checking the size of a type

AC_CHECK_SIZEOF(uid_t)
if test $ac_cv_sizeof_uid_t = "4"; then
...
fi

Checking the endianess of a platform



AC_CHECK_HEADERS([endian.h],
 AC_TRY_COMPILE([#include <endian.h>], [switch (1) { case __LITTLE_ENDIAN: break; case __BYTE_ORDER: break; } ],[is_little_endian=0], [is_little_endian=1]),
 AC_MSG_ERR([Can't Determine Endianess])
)
if test $is_little_endian = 1 ; then
...
fi

A Simple configure.ac

For those that just want a quick start, below is a simple configure.ac file

#
# A good reference for macros for this config file is at:
# http://sourceware.org/autobook/autobook/autobook_283.html

AC_PREREQ(2.50)

AC_INIT(PROJECTNAMEHERE, VERSIONHERE, EMAILADDRESSHERE)

# Define where autogenerated build files such as 'missing'
# should be located. This is also the location of any additional
# m4 macros that are required
AC_CONFIG_AUX_DIR(cfg)

#
# Init Automake subsystem
#
AM_INIT_AUTOMAKE(PROJECTNAMEHERE,VERSIONHERE)
AM_CONFIG_HEADER(config.h)

# Indicate this is a release build and that
# dependancies for changes between Makefile.am and Makefile.in
# should not be checked. This makes compiling faster. If you are working
# on the library, run: ./configure --enable-maintainer-mode to enable the dependancies
dnl AM_MAINTAINER_MODE

# Need the C++ Compiler, Installer and ranlib to strip libraries
#
AC_PROG_CC
AC_PROG_CXX
AC_PROG_INSTALL
AC_C_CONST
AC_C_INLINE
AC_TYPE_SIZE_T

AC_CONFIG_FILES([Makefile])

AC_OUTPUT

A Simple Makefile.am

Here’s a simple Makefile.am that can be used in the root directory of a project

# Indicate this is not a GNU project and that
# missing files should be automatically created
AUTOMAKE_OPTIONS=foreign

# Instruct aclocal to check the cfg directory for
# extra macros
ACLOCAL_AMFLAGS=-I cfg

INCLUDES= -I@top_srcdir@

# Global C Flags
#AM_CFLAGS = 

#EXTRA_DIST=libwcl.pc

# Programs to build
bin_PROGRAMS = evaluateTablet

# Evaluate Table Application
evaluateTablet_includedir=@top_srcdir@
evaluateTablet_LDADD=-l
evaluateTablet_SOURCES=.....

References

1. ↑ http://www.gnu.org/software/automake/manual/html_node/Invoking-aclocal.html
2. ↑ http://www.gnu.org/software/autoconf/
3. ↑ http://www.gnu.org/software/automake/
4. ↑ http://www.gnu.org/software/autoconf/manual/autoconf-2.57/html_node/autoconf_29.html
5. ↑ http://www.gnu.org/software/libtool/