how-to-build-ia2-idl.txt

Setup

After cygwin install had to
- install the cygwin zip utility (in the Archive category)
- install openssh and rsync (in the Net category)
- run this at the command prompt
    mkpasswd -l > /etc/passwd
    Note: On a later install on another machine I didn't have to do this

Had to update my doxygen.conf from 1.5.8 to 1.8.2 (to be compatible with the latest version) using
  doxygen -s -u doxygen.conf (-s = no comments, -u = update)
  Note: If the config file spec hasn't changed this won't be necessary

If you only need the merged IDL file for your project:
- Just run concatidl.sh -- there is no need for Doxygen in this case

How to build the IA2 docs, a merged IDL file, a zip file containing the docs and IDL files.
- The directory tree...
  - ia2 contains:
    - this file
    - buildapi.sh: the build script (need cygwin bash shell interpreter installed)
    - doxygen.conf: the doxygen config file (tweaked from the doxygen distribution)
    - doxygen.css: the doxygen css file (tweaked from the doxygen distribution)
    - header.html: contains metadata
    - footer.html: contains the footer seen on each page
    - ia2-<version>-errata.html: info about changes and bug reporting
    - changelog.txt: lists changes made since the last release
    - a merged IDL file with all the IDL concatenated together
    - a zip file containing IDL and doxygen output
    - an api directory which contains the IDL
    - a docs directory which contains the doxygen generated output
    - an IDL-Test directory which contains Visual Studio files for testing:
      - for VC6
        - IA2 IDL Test.dsw/dsp, IA2 Merged IDL Test.dsp, StdAfx.cpp/h
      - for VC 2008 Express
        - IA2 IDL Test.sln/vcproj, IA2 Merged IDL Test.vcproj, StdAfx.cpp/h
- The build procedure
  - don't forget to change the version number in doxygen.conf, header.html, and IA2TypeLibrary.idl
    note: the type library version number can only be in major.minor format, e.g. not 1.2.1.
  - create a new errata file; don't forget to change the version and date
  - update header.html and footer.html, e.g. date, version #; also doxygen version #
  - don't forget to create a changelog.txt file
  - start cygwin
  - CD to the directory containing the above files
  - sh buildapi.sh >sh.out
  - notepad sh.out (to check for errors)
  - exit cygwin
  - the doxygen generated files, merged idl file, and the zip file will be built
  - move to the IDL-Test directory
  - activate the sln file
  - There are two projects, one for the individual idl files, one for the merged idl file
  - Build, Batch Build, Choose the non-merged IDL project
  - Fix any errors, save the fixes, and rebuild the project.
  - If there were errors, rebuild the merged file by rerunning buildapi.sh
  - Build, Batch Build, Choose the merged IDL project
  - Fix any errors in the original source IDLs or buildapi.sh that caused the problem
  - Rerun the buildapi.sh build script.
  Note: Don't fix errors in the merged file; fix them in the correct source file.
- Build the proxy DLL
  - Use resedit and update the version number of IAccessible2Proxy.rc
    - You will have to point resedit at the windows.h file from a Windows SDK
    - I used the SDK for v7.1A
  - Use Visual Studio 2012 Express Edition to build the solution.
  - Put the project files on the web site:
    - IAccessible2Proxy.def
    - IAccessible2Proxy.rc
    - IAccessible2Proxy.sln
    - IAccessible2Proxy.vcxproj
    - resource.h
  - Put the generated DLL on the web site:
    - IAccessible2Proxy.dll