V20VersionABIChanges

DRAFT WORK IN PROGRESS

This page is about changes to the version API. We are in the process of revising this API for PA V20. See the References section at the end for links to mailing list discussions and tickets.

h2. Existing V19 version interfaces

The public "official" PA V19 source version numbering is based on the timestamp of the stable or nightly tarball, e.g. pa_stable_v19_20140130.tgz

The V19 API provides the following two functions to query the API version (see "portaudio.h":http://portaudio.com/docs/v19-doxydocs/portaudio_8h.html, originally added via "this proposal":http://www.portaudio.com/docs/proposals/018-VersionInformationInterface.html):

int 	Pa_GetVersion (void)
const char * Pa_GetVersionText (void)

Note: Pa_GetVersion has so far always returned 1899 and is hence not very useful. The content of Pa_GetVersionText() is not strictly specified and could be changed or improved.

Some PA structs have a structVersion field. These structVersion fields have not been consistently updated when structs were modified -- therefore they are not a very reliably mechanism.

The following structs contain structVersion fields:

"PaHostApiInfo":http://portaudio.com/docs/v19-doxydocs/structPaHostApiInfo.html "PaDeviceInfo":http://portaudio.com/docs/v19-doxydocs/structPaDeviceInfo.html "PaStreamInfo":http://portaudio.com/docs/v19-doxydocs/structPaStreamInfo.html

These structs don't:

"PaHostErrorInfo":http://portaudio.com/docs/v19-doxydocs/structPaHostErrorInfo.html "PaStreamParameters":http://portaudio.com/docs/v19-doxydocs/structPaStreamParameters.html "PaStreamCallbackTimeInfo":http://portaudio.com/docs/v19-doxydocs/structPaStreamCallbackTimeInfo.html

Host-API specific data structures may also have some kind of versioning field. e.g PaAsioStreamInfo has a size field rather than a structVersion field:

"PaAsioStreamInfo":http://portaudio.com/docs/v19-doxydocs/structPaAsioStreamInfo.html

TODO: review other host-API specific structs.

h2. Requirements (in no particular order)

The purpose of this section is to list requirements and uses for version API features. It is intended to be exhaustive so that we can assess interactions between requirements.

h3. A sane version number system that we can use to refer to releases. e.g. "20.0.1"

why? what is this used for? ??? what reasons have people given for wanting this?

It is desirable to also use this version number for code-based checks (compile time and runtime).

h3. An API for retrieving the version number of the current executing PortAudio

Allows the user of a program to report running version for debugging [must-have]

• Provide a policy and a run-time mechanism that allows the client program to determine API/ABI compatibility when loading a shared library [desirable?]

E.g. allows the client program to fail if API/ABI version is not compatible. (this may simply mean matching ABI versions, or we may provide backward compatibility within a major version -- need to specify)

Answers question: can I use this shared library?

h3. Provide a policy and a run-time mechanism that allows the client program to determine API/ABI availability when loading a shared library [desirable?]

Answers question: does this struct have the expected format? does it have an expected field? Considerations:

• function signatures (number and types of params and return values)
• layout of structs
• availability of fields in structs

h3. Compile-time macros for testing the version number

Allows conditional compilation of client code so that it uses PA features only if they are available and/or allows conditional compilation of clients against multiple incompatible PA APIs.

h3. ability to print SVN version number at runtime

Assists with debugging.

h2. Misc Considerations

We need to establish a revision controlled document that describes ABI changes when they are made (ABICHANGES.txt ?)

We need a policy about when ABI changes will be made (major/minor version number increments)

h2. Proposals

h2. Alternatives not taken

h2. Additional dependencies / related changes

h2. References

#173 "Improved API library version API":https://www.assembla.com/spaces/portaudio/tickets/173

#172 "Remove structVersion field from PaHostApiInfo, PaDeviceInfo and PaStreamInfo":https://www.assembla.com/spaces/portaudio/tickets/172

#174 "[META] ABI/API changes before V19 final release":https://www.assembla.com/spaces/portaudio/tickets/174

• #58 API calling convention and pack
• #169 Portaudio should expose host API specific stream information
• #172 Remove structVersion field from PaHostApiInfo, PaDeviceInfo and PaStreamInfo
• #173 Improved API library version API
• #225 PA should expose host API specific device information