Proposed Enhancements to PortAudio API

021 - New Directory Structure

Enhancement Proposals Index, PortAudio Home Page

Updated: February 20, 2004


This proposal is under consideration by the PortAudio development community.


The directory structure currently being used was designed at a time when each implementation was separate, and so had its own directory. Since then a lot more code is shared in a common directory, and now there is code which is common to a platform, and shared by multiple implementations. There is also a requirement to accomodate multiple language bindings. Some people considered the pa_* prefix on each directory as being redundant.

See discussions on mailing list around October 10 2003 and before.

The issue was raised again at the end of January 2004:


The proposal is to use the directory structure listed below. Although it is not the goal of this proposal to undertake any major source-file name changes, 'wmme' will be changed to 'mme' to be more consistent with industry standards ("wmme sound" occurs < 100 times in Google, while "mme sound" has over 56000 entries).

/[gnu configure + makefiles in root directory]

    /html               (doxygen generated HTML documentation)
    /src                (doxygen source files)

/include                (public include files)
    pa_mme.h            (mme specific extensions)
    pa_asio.h           (asio specific extensions)

    /common             (portable common infrastructure)
    /os                 (code common to a particular platform)
    /hostapi            (code for each host api)
        /al             (IRIX al)
        /sm             (MacOS sound manager)

/tests                  (test files)

/build                  (static makefiles/project files for toolsets that don't ./configure)



The current proposal is to only put public include files in the top level /include directory, with implementation include files being left in /common. Some people thought this could be confusing, but it has the advantage of clearly separating PortAudio's "public interface" from its implementation internals. It was noted that the GNU configure way is to support "exported" and "private" include files in a single include directory.

It was suggested that we remove the /src directory and place common/, os/ and hostapi/ in the root directory. The argument for this is that it makes things easier to find. On the other hand, it is good to make a clear distinction between the source, auxilliary documentation, interface headers, build configuration files and foriegn language bindings.

Impact Analysis

The configure, project and Makefiles will need to be adjusted to accomodate the new directory structure. CVS history will be lost, although this was likely to be the case anyway with the merge back onto the HEAD.