michael@4: Tunnelblick Build Notes
michael@4: Michael Schloh von Bennewitz
michael@4: 28 July 2009
michael@4: ----------------------------
michael@4: 
michael@4: These instructions for building Tunnelblick describe a release
michael@4: engineering environment using Mac OS X 10.5.7, XCode 3.1.3, and
michael@4: the API from 'MacOSX10.5.sdk'.
michael@4: 
michael@4: Workflow
michael@4: 
michael@4: - Read the project's source building guidance [01] documentation.
michael@4: - Fetch the latest Tunnelblick sources [02] from SVN.
michael@4: - Fetch the third party software [03][04][05][06] distributions.
michael@4: - Possibly test Growl [07] integration (not sure if integrated.)
michael@4: -
michael@4: - Unpack the Tunnelblick source distribution.
michael@4: - Change directory to tunnelblick/third_party
michael@4: - Move all dirs (sparkle, lzo, pkcs11, tuntap, openvpn) away.
michael@4: - Unpack the freshly downloaded third party distributions. Be
michael@4:   careful to use the Sparkle source code rather than binary.
michael@4: -
michael@4: - Replace the Makefile [08] and inspect the differences.
michael@4:   Pay attention to the versions of unpackaged software
michael@4:   distributions and those hard coded in the Makefile.
michael@4: - Move 'openvpn-<version>' to simply 'openvpn'.
michael@4: - Execute make as usual [09].
michael@4: - Inspect the resulting universal binaries [10].
michael@4: -
michael@4: - Change directory to tunnelblick/tunnelblick
michael@4: - Start XCode, usually found in /Developer/Applications/Xcode.app/
michael@4: - Load the Sparkle XCode project and build the Sparkle.framework [11].
michael@4: - Load the Tunnelblick XCode project file Tunnelblick.xcodeproj [12].
michael@4: - Change the target to 'Release' as suggested in [01].
michael@4: - Clean and build the product as usual, pressing the build button.
michael@4: - Verify the build result, warnings can be expected and are normal.
michael@4: - Inspect build/Release/Tunnelblick.dmg by mounting it and verify
michael@4:   that the directory contents of Tunnelblick.app correspond to the
michael@4:   OS X application bundle standard hierarchy.
michael@4: -
michael@4: - Read the companion document to this one 'tunnelblick_install.txt'.
michael@4: - Inspect the directory contents of ~/Library/openvpn and
michael@4:   ~/Library/Preferences/com.openvpn.tunnelblick.plist.
michael@4: - Install by copying Tunnelblick.app to /Applications/.
michael@4: - Execute from a terminal as usual [13].
michael@4: - Compare the directory contents and preferences with previous results.
michael@4: 
michael@4: [01] http://groups.google.com/group/tunnelblick-discuss/web/compiling-tunnelblick-from-source
michael@4: [02] http://tunnelblick.googlecode.com/svn/trunk/
michael@4: [03] http://www.oberhumer.com/opensource/lzo/download/
michael@4: [04] http://www.opensc-project.org/files/pkcs11-helper/
michael@4: [05] http://freefr.dl.sourceforge.net/sourceforge/tuntaposx/tuntap_20080804.tar.gz
michael@4: [06] http://sparkle.andymatuschak.org/files/
michael@4: [07] http://www.growl.info/
michael@4: [08] http://scm.europalab.com/tunnelblick/thirdparty/Makefile
michael@4: [09] $ time make 2>&1 | build.txt
michael@4: [10] $ lipo -info tuntap/tun.kext/Contents/MacOS/tun \
michael@4:                   pkcs11-helper-1.07/staging/lib/libpkcs11-helper.a \
michael@4:                   lzo-2.03/staging/lib/liblzo.a \
michael@4:                   openvpn/openvpn
michael@4: [11] Changes to the buildconf are needed, see project files in SCM.
michael@4: [12] Changes to the buildconf are needed, see project files in SCM.
michael@4: [13] $ /Applications/Tunnelblick.app/Contents/MacOS/Tunnelblick
michael@4: 
michael@4: ----
michael@4: 
michael@4: Tunnelblick Installation Notes
michael@4: Michael Schloh von Bennewitz
michael@4: 28 July 2009
michael@4: ------------------------------
michael@4: 
michael@4: Tunnelblick contains a system independent self built copy of OpenVPN,
michael@4: which is statically linked to the LZO and PKCS11Helper libraries. The
michael@4: OpenVPN configuration is found in:
michael@4: 
michael@4:   ~/Library/openvpn/openvpn.conf
michael@4: 
michael@4: ...which may eventually conflict with other software installations.
michael@4: 
michael@4: Tunnelblick contains a system independent self built copy of TUN/TAP.
michael@4: This means that Tunnelblick does not use the TUN/TAP drivers of other
michael@4: products, most notably the main vendor's:
michael@4: 
michael@4:   /Library/Extensions/tap.kext
michael@4:   /Library/Extensions/tun.kext
michael@4:   /Library/StartupItems/tap
michael@4:   /Library/StartupItems/tun
michael@4: 
michael@4: Tunnelblick user preferences are stored in:
michael@4: 
michael@4:   ~/Library/Preferences/com.openvpn.tunnelblick.plist
michael@4: 
michael@4: Tunnelblick certificates are stored in:
michael@4: 
michael@4:   ~/Library/openvpn
michael@4: 
michael@4: Because Tunnelblick encapsulates all software components and drivers
michael@4: that it needs in the Tunnelblick application bundle, to uninstall simply
michael@4: delete the application bundle named Tunnelblick.app.
michael@4: 
michael@4: Manifest
michael@4: 
michael@4:   /Applications/Tunnelblick.app/
michael@4:   ~/Library/openvpn/*
michael@4:   ~/Library/Preferences/com.openvpn.tunnelblick.plist