View source for Build a MacOSX Universal Hugin bundle with Xcode

'''''THIS IS STILL A DRAFT VERSION'''''

=='''Introduction'''==

The "normal" way of compiling Hugin is via Cmake. With the current versions of MacPorts, fink and Cmake it is very difficult to make a universal bundle due to the way [[#Additional documentation| endianness]] is dealt with in MacPorts and Fink. This HowTo explains how to make a universal bundle with Xcode.

The creation of a bundle is actually a two step process:
# '''Build all libraries and binaries which Hugin depends on.''' This is done outside Xcode. From here on we will call these libraries and binaries "External Programs". To compile and build all "External Programs" as universal, we will follow a different process compared to the normal "straight-forward" process of building libraries with MacPorts or Finks as described in [http://wiki.panotools.org/Hugin_Compiling_OSX Hugin Compiling OSX]. We do not need nor use MacPorts and/or Fink. What's more: We even need to get it "out of the way".
# '''Build Hugin and it's "internal" tools in Xcode and create the bundle.''' As the title suggests: This is done in Xcode.

''Note:'' This Howto does not explain how to build a Hugin the "cmake way". Follow the Howto [[Hugin_Compiling_OSX | Hugin Compiling OSX]].

=='''Prerequisites'''==
===Download and install XCode===
[http://developer.apple.com/tools/download/ Download] and install the XCode Tools version for your MacOSX version: Xcode 2.4.x for MacOSX 10.4.x or below and Xcode 3.x for 10.5.x (Leopard). For those who are brave enough to ponder into the dark corners of the installed base: You will find a 4.x version and a 3.3 version of the GNU compiler and it's "companions". Do not remove either of them. The 4.x version is used for i386/X_64 builds and the 3.3 version is used for the "older" PPC builds. You need both to be able to build a [http://en.wikipedia.org/wiki/Universal_binary Universal binary] (No matter whether you use XCode only or Xcode as basis for MacPorts or Fink).

===Install CMake===
Get and install the build system CMake, version 2.4.7 or later, from [http://www.cmake.org/HTML/Download.html CMake].

===Subversion (SVN)===
Leopard comes with SVN installed. If you are on Tiger or below you need to build it yourself. The simplest way to get SVN is to use your MacPorts or Fink version. (Yes, I know. I said that you did not need MacPorts or Fink. I'll come back on it later).<br />
If you fancy a nice GUI you can download the Open-Source [http://www.lachoseinteractive.net/en/community/subversion/svnx/features/?sid=b42441f308810ad0d36b779f90319391 SVNX]. You still need svn installed as it is only a graphical shell and I won't explain SVNX here (I only used it once, I still like the terminal).


=='''Preparations for building the "External Programs"'''==
===Introduction===
Building the necessary "External Programs" (the libraries and binaries Hugin depends on) is completely scripted. This part describes not how to use "<tt>.configure</tt>" or "<tt>make; make install</tt>". It will explain (advise) how and where to create the necessary directory structure, configure the base environment script and, more or less, tell you in which order to run the package build scripts.

===Location of the "External Programs" development tree===
To start with: This part describes where we want to place the development tree for our "External Programs" where hugin depends on. This does not necessarily need to be in the same place as the Hugin source itself although the "External Programs" directory structure is by default placed inside the Hugin SVN tree when you download Hugin.<br />
The first question is: Where do you ''want'' to have your development tree? As you (might) know, the "normal" locations are <tt>/opt/local</tt> for MacPorts, <tt>/sw</tt> for Fink and finally <tt>/usr/local</tt> for all builds following "Linux" rules. '''We do not want to use these locations'''! Apart from the fact that it is a bad idea to mix up development trees, another drawback is that these directories are not in "user space", therefore always requiring a root authorization, e.g. "<tt>sudo make install</tt>" as a last step. 
When keeping the development tree in user space (e.g. <tt>/Users/<your_username>/development/</tt> or <tt>/Users/Shared/development/</tt>), you don't need to "sudo". Note that I also create and use a <tt>development</tt> directory to keep it away from my "normal" user data.<br />
So, from this moment "we" have decided to build our development tree in user space.<br />
''Note'': If you position your development tree '''outside''' user space, you need to run ''everything'' as sudo. The scripts are not tailored towards that "sudo" kind of use and need modification to work that way.

====Inside hugin SVN tree====
The "External Programs" development tree is placed inside the hugin SVN tree when you download Hugin. After you downloaded Hugin from SVN, you will find inside the <tt>hugin</tt> directory the following directory structure:
<blockquote><tt>
hugin<br />
:/...other directories inside hugin<br />
:::/'''mac'''<br />
::::'''/Documents'''<br />
::::'''/ExternalPrograms'''<br />
:::::::::'''/scripts'''<br />
:::/<more files inside mac>
:/...other directories inside hugin<br />
</tt></blockquote>
Say you have downloaded hugin in <tt>/Users/<your_username>/development</tt> (Remember that "we" decided to keep it in user space?), than your "External Programs" build tree will be inside <tt>/Users/<your_username>/development/hugin/hugin/mac/ExternalPrograms/</tt>.
''Note'': You will also find a <tt>mac<tt> directory inside the <tt>platforms</tt> directory. This <tt>hugin/platforms/mac/</tt> directory is meant for user added tools like [http://www.erik-krause.de/ Erik Krause's] droplet scripts, which you will find in <tt>platforms/windows</tt>.

====Outside Hugin SVN tree====
Based on what I explained above you could also decide to place your build tree for the "External Programs" ''outside'' the hugin SVN tree. An option might be <tt>/Users/<your_username>/development/ExternalPrograms/</tt>.

<blockquote>'''Pro's and Cons of "outside" Hugin SVN tree'''<br />
''Pro's:''
* You have your "External Programs" build tree separate from the hugin source. You can delete and recreate the Hugin SVN directory anyway and anytime you want without touching your carefully built "External Programs".
* If you plan to build more universal software using this approach, you can share this directory (or just as well build another one).<br />
''Cons:''
* If updates in SVN are applied to the "External Programs" build scripts, you need to track that and manually copy these to your separate build tree.</blockquote>
(Currently I have my "External Programs" build tree inside hugin as I started it this way. I once needed to delete my hugin SVN tree and I first moved my <tt>mac</tt> directory (including <tt>ExternalPrograms</tt>) out of the way, deleted the hugin svn tree, downloaded the new hugin svn tree, moved the <tt>mac</tt> directory back inside and svn synced hugin again to get possible changes in the mac or scripts directory. You just have to remember that you need to do that.)

===Creation of the "External Programs" development tree===
If you leave the "External Programs" development tree inside the Hugin SVN tree, you don't have to do anything and for simplicity this HowTo focuses on that way of working. <br />
If you want to create it outside the hugin svn tree, I advise you to first create a <tt>development</tt> directory inside your home directory and to create the <tt>ExternalPrograms</tt> directory inside that <tt>development</tt> directory.<br />
As mentioned: This HowTo focuses on keeping it in the Hugin svn tree. You need to change the paths as mentioned in the rest of this HowTo, according to your choices.

===Prepare the build environment===
Our build environment uses a lot of preset environment variables. These variables are all set by calling a text file. This text file is "<tt>SetEnv-universal.txt</tt>". You can find this file inside <tt>hugin/mac/ExternalPrograms/scripts</tt>.
In the top of this file you will find the following two lines:
<pre># has to be the absolute path from /
myREPOSITORYDIR="/Users/Shared/development/hugin_related/hugin/mac/ExternalPrograms/repository";</pre>
The path in the <tt>myREPOSITORYDIR</tt> variable needs to exactly match the path you use (This example show the (current) default one from the SVN). So, if you are Spiderman and you build inside your HOME directory you need to specify:
<pre>myREPOSITORYDIR="/Users/spiderman/development/hugin/mac/ExternalPrograms/repository";</pre>
Check it, and check it again !!<br />
You do not need to modify anything below this line.
*''64bit (Leopard) versus 32bit (Tiger)''<br />
::Tiger (Xcode 2.4) enables you to build universal binaries and libraries for PPC and i386. Leopard (XCode 3.0) enables you to build universal binaries for PPC and i386, but also for PPC_64 (theoretically) and X86_64. If you want to do this you need to use SetEnv-leopard.txt. At this moment this is "''extremely and utterly experimental''" as:
::# most "Linux derived" libraries and binaries are not optimized yet for Apple 64bit, let alone that they will compile for 64bit. 
::# only enblend can use the full potential of 64bit (currently)
::# You build the 64bit part only for Leopard users on 64bit hardware. 32bit universal will run on ''every'' Mac.
::# The current bundle is 85 MB. If you build for three architectures (ppc/i386/x86_64) it will be approx 120 MB.
:Use at your own risk. Or better, for the time being: stay away from it.


=='''Building the "External Programs"'''==
===Building Subversion (SVN)===
''(Note: Tiger and earlier only)''<br />Before being able to download Hugin from svn we need to have svn in place. If you are on Leopard (MacOSX 10.5.x), you are fine and you can skip this step. If you are on Tiger (MacOSX 10.4.x) or an earlier version you need to build it yourself.<br />
You first need to [[Hugin_Compiling_OSX#Install_Macports | Install Macports]] (if you did not already do so) as described in [[Hugin_Compiling_OSX | Hugin Compiling OSX]]. Then you need to install Subversion (svn) like:
<blockquote><pre>$ sudo port install subversion</pre></blockquote>

===Get Hugin from SVN===
Cd into your development tree and download hugin from svn like: <blockquote><pre>$ cd ~
$ cd development
$ svn co https://hugin.svn.sourceforge.net/svnroot/hugin/hugin/trunk hugin</pre></blockquote>
Inside <tt>/Users/<your_username>/development</tt>, you will now have a directory <tt>hugin</tt>. The full path to your "External Programs" development tree will be <tt>/Users/<your_username>/development/hugin/mac/ExternalPrograms</tt>.

===Get MacPorts and/or Fink out of the way===
Now we really need to get MacPorts and/or Fink out of the way. We want to make a completely separate development tree. This means that we do not want to link to any library or binary outside our "External Programs" development tree (unless they are true Mac system libraries that are part of your MacOSX version). If we accidentally ''do'' link to non-system libraries outside our tree we will have problems when we build the bundle and certainly when we want to distribute it. So to get them out of the way, we do the following:
<blockquote><pre>$ sudo mv /opt /opt.org
$ sudo mv /sw /sw.org
$ sudo mv /usr/local /usr/local.org</pre></blockquote>
Note: The <tt>usr/local</tt> is in case we built libraries or binaries without MacPorts or Fink.<br />
'''Note 2: Do not use "<tt>sudo mv /usr /usr.org</tt>" as <tt>/usr</tt> is vital for proper system functioning!!!''' If you accidentally do this, you need to reboot using your Mac DVD, go into the terminal and move it back.


===Build the "External Programs"===
Building the necessary libraries and binaries which Hugin depends on, the so called "External Programs" is now relatively easy.
* You <tt>cd</tt> into your ExternalPrograms subdirectory, like <blockquote><pre>cd /<path_to>/ExternalPrograms</pre></blockquote>
* Download the necessary source packages (Google for it, copy them from your MacPorts and/or Fink base if available). The script names tell you which ones you need.
* untar/unbzip2 the source packages. It's best to do this in the ExternalPrograms directory so that you will have all kind of subdirectories containing the source, like jpeg-6b, tiff-3.8.2, enblend, wxMac-2.8.7 and so on.

And as an example for libpng:
<blockquote><pre>$ bunzip2 libpng-1.2.24.tar.bz2
$ tar -xvf libpng-1.2.24.tar
$ cd libpng-1.2.24</pre></blockquote>


As mentioned in [[Prepare the build environment]] we need to set our build environment before we can start compiling our libraries and binaries.
This setting can be done anywhere from the system and doesn't need to been done from our library directory.
But assuming we are still in our libpng directory we issue the command:
<blockquote><pre>$ source ../scripts/SetEnv-universal.txt</pre></blockquote>

Now we can really start building our libraries and binaries. You do this by calling the right shell compilation script (still using libpng as an example).
<blockquote><pre>$ sh ../scripts/libpng.sh</pre></blockquote>


===Order of building the "External Programs"===
Some libraries and programs are dependent on other libraries. This means that these libraries need to be built first. As a rule of thumb, build your libraries in the following order (shell script names): 
libjpeg.sh, libtiff.sh, libpng.sh, expat.sh, lcms.sh, ilmbase.sh, openexr16.sh, boost.sh, wxmac28.sh, pano13.sh, libexiv2.sh

And for the binaries:
gnumake.sh, autopano-sift-C.sh, enblend31.sh, panomatic.sh

''Note: You need to examine the scripts before executing them as some script use major and minor library numbers. These numbers are set from the script and need to be changed if your library version changes.''

===Cleaning up===
Apart from the wxmac (wxwindows) source tree, you can remove every library source tree if you want to. 
The wxmac source tree is necessary for the Xcode project. Xcode needs the “localization” source files.
When you are finished building you can also reinstate the Macports or Fink directories you had disabled (see [[Get MacPorts and/or Fink out of the way]]).


 

==Xcode compiling Hugin==
===XCode basic walk-through===
This HowTo will not discuss how to use XCode. It will only explain some very basic steps to get you going. The rest is up to you (''Xcode - the Final Frontier...............To boldly go where no man has gone before.'')
Sometimes small changes need to be made to the Xcode project due to added tools (matchpoint recently) or added or removed source files. These kind of actions will not be explained either in this HowTo.
 
When you double-click the hugin.xcodeproj, Xcode will start and show you the following screen: 
In the Top section you see the Menu/Toolbar.
On the left side you see the navigation panel.
On the right side you see the File section.<br />
[[Image:Xcode screen.png|600px|Xcode screen layout]]

 



<br /><br /><table border="0" width="600"><TR><TD>[[Image:Xcode files section.png | 229px | left | frame | Xcode "files" section]]</TD><TD valign="top">In the left Navigation panel you see little triangles in front of the icons and their descriptions. These triangles can be used to open or close the sub-sections. Double-clicking the icons has another function and will bring you to the properties of that subsection. If you click the little triangle in front of Hugin, you see the directory structure of the files the Hugin project uses. Please note that this is not a real representation of the hugin directory but a user-created representation. Note however that the "files" in here are actually links to your real files. If you double-click them, the Xcode editor will open them for editing and save them back to the file system.<br /><br /></TD></TR>
<TR><TD>[[Image:Xcode targets section.png | 180px | left | frame | Xcode Targets section]]</TD><TD valign="top">Below the Hugin icon/description, you'll find the Targets section.  Here you need to define what needs to be compiled, linked, copied and so on to create a binary or library, or a bundle containing these binaries and libraries. In case of a complex build project like Hugin, you first need to compile underlying tools and libraries, than build hugin and link hugin against these underlying tools and libraries, and finally create the bundle including "some copy work" to get the "External Programs" like autopano-sift-c, panomatic, the PT* tools, enblend, enfuse and the like inside the bundle.</TD></TR></TABLE>
Other options in the Navigation panel are not relevant or interesting, although you might see the error part quite frequently in your early attempts.

===Prepare the project for our configuration===
You need to tell the project where you installed your "Hugin friends" libraries and binaries (wxmac, boost, libtiff and so on) to be able to compile Hugin. Also a couple of shell scripts need to be adapted. This can all be done from inside Xcode.

The first thing to do is to double-click the blue icon before Hugin [[Image:Xcode huginproject icon.png]] in the top-left corner of the Navigation pane. If you do this, the following screen will open.<br />
[[Image:Hugin projectinfo general.png | 700px]]<br />
This "General" tab the location where your Hugin.app, and the intermediate files, will be built. By default a build directory will be created in the same directory where your Hugin.xcodeproj resides. If you want another location you can change that here, but unless you know what you're doing leave it as it is.<br /><br />
The second tab is the "Build" tab (see below).<br />
[[Image:Hugin projectinfo build.png | 700px]]<br />
You need to check, and if necessary change, the values for:
* Library Search Paths
* REPOSITORY_DIR
* WX_INCLUDE_DIR
* WX_INCLUDE_DIR_LIB
* WX_MAJOR_VERSOIN  (note that it says VERSOIN in stead of VERSION. Leave it like that!)
All path's are relative to the location of the hugin.xcodeproj directory structure. If you did build the libraries that Hugin depends on according the steps described above, you do not need to change anything. But do check!

The other tabs are not relevant, but feel free to expand your knowledge.

===Prepare the scripts before building===
<table border="0" width="600"><TR><TD>[[Image:Xcode script preparation.png | left | frame | 271px | Some of the necessary scripts]]</TD><TD valign="TOP"> The project uses a couple of shell scripts to get everything into the bundle. In a Xcode project you can define steps for this in your targets. These steps then consists of these scripts.
Note though that if these scripts are not correct, Xcode will generate a non-fatal error. However, this non-fatal error for Xcode will quite often be a fatal error for your final bundle as it will miss "something"  and it will simply not run or not run correctly.
Take a look at the target Hugin: Open Targets -> Hugin and double-click (for example) the entry "Complete bundle". This will show you how to embed scripts.
Note however, that you do not edit the scripts from the Target(s) position. You edit the script inside the files section (see [[XCode basic walk-through]]). In this project everything is already at it's correct position. </TD></TR></TABLE>


 



====Edit localised.sh====
Move (back) in the navigation pane to the top of your project and open the top section (the "file"  section), open the <tt>mac</tt> "directory" and locate <tt>localised.sh</tt>. Double-click <tt>localised.sh</tt> to open it.
In the top of the script you will find the following lines:
<pre>huginVer="$HUGIN_PACKAGE_VERSION"
wxDir="./ExternalPrograms/wxMac-2.8.7"
resdir="$TARGET_BUILD_DIR/Hugin.app/Contents/Resources"
huginsrcdir="../src/hugin1/hugin"
xrcsrcdir="$huginsrcdir/xrc"
translationsdir="../src/translations"
</pre>
Change the <tt>wxDir</tt> to the directory where your wxmac '''source code''' resides.
Click (Menu) File->Save or <Command>-S  to save the script. Close it.

====Edit Complete-bundle.sh====
Locate the <tt>Complete-bundle.sh</tt> script and double-click to open it. In the top of the script you will find the following lines:
<pre>dylib_dir="../mac/ExternalPrograms/repository/lib"
old_install_name_dirname="/Users/Shared/development/hugin_related/hugin/mac/ExternalPrograms/repository/lib"
dylib_install_loc="Libraries"
new_install_name_dirname="@executable_path/../$dylib_install_loc"
</pre>
Change the <tt>dylib_dir</tt> to the correct relative path.<br />
Change the <tt>old_install_name_dirname</tt> to the correct '''absolute''' path.
Click (Menu) File->Save or <Command>-S  to save the script. Close it.

====Edit copyExifTool.sh====
If you have Exiftool on your system, you need to edit this script too. As mentioned in the early lines of [[Prepare the scripts before building]] Xcode will generate a non-fatal error if Exiftool is not available (or you configured the script incorrectly), but in this case Hugin will run without it as it is an "extra"  tool and Hugin can run without it.<br />
Locate the <tt>copyExifTool.sh</tt> script and double-click to open it. In the top of the script you will find the following lines:
<pre>exiftoolDir="./ExternalPrograms/Image-ExifTool-7.25"
resdir="$TARGET_BUILD_DIR/Hugin.app/Contents/Resources"
</pre>
Change the <tt>exiftoolDir</tt> path to the path where your Exiftool resides.<br />
Click (Menu) File->Save or <Command>-S  to save the script. Close it.


===Compile and build our Hugin.app===
====Final check====
We make one final check.<br />
[[Image:Xcode configure build.png|512px]]


Set the "Active Target"  to "configure" and "Active Build Configuration"  to "Release". Now click the "Build" icon. This will only take a few seconds or less. In the status bar you will see the message concerning this step. It should say "Build succeeded"  on the left and "Succeeded" on the right.<br />
[[Image:Xcode configure build success.png|800px]]

If this is the status message, you can really start building your Hugin.app.

====Building Hugin.app====
Set the "Active Target"  to "all" and click "Build".  Now this will take a very long time.<br />
[[Image:Xcode build all.png|512px]]


If everything compiles and builds correctly, you will finally get a status message like:<br />
[[Image:Xcode build all success.png|800px]]


Note that the build has succeeded even though you see two error messages (in this screen dump). These are the non-fatal errors mentioned before. Double-click the "error" icon [[Image:Xcode error icon.png]] to display the errors.
In this case it mostly means that some language files (*.po) could not be found. The available languages (= *.po files) differ between Hugin and wxmac, the scripts can not solve this entirely and will generate errors. These *.po errors are non-fatal errors for the Hugin.app. Hugin or wxmac will simply not be able to show messages/text in that language and will fall back to English.

If you did stick to all the "default settings", you will find your Hugin.app inside <tt>../mac/build/Release</tt> among lots and lots of other files. All these other (intermediate build) files are not relevant. If built correctly, the Hugin.app is a completely portable application and everything is inside Hugin.app. <br />


====Testing Hugin.app====
Now you need to test run your bundle. The first test is to see whether your application runs at all. Double-click it and try to make a panorama. If this works, it's party time!!!  So, go party and when you're finished come back for the next test.<br />

Now that you managed to get a working Hugin.app via Xcode we need to check if it is really a portable application.
If you were ''completely'' successful in building your Hugin.app, than all binaries, tools and libraries should be "inside"  the bundle and should know "how to find each other". The best way to test this is to copy the Hugin.app to another Mac and run Hugin.app there. As this is not always possible, copy your Hugin.app to another location on your mac and rename<br />
* your mac directory inside your hugin source directory to mac.org,
* your /opt/local to /opt/local.org (in case you have Macports),
* your /sw directory to /sw.org (in case you have Fink),
* your usr/local directory to /usr/local.org 
(You can off course rename your directories to anything you like). 
Renaming your directories will prevent Hugin from trying to link to the libraries inside these directories. If Hugin does that you will get error messages that Hugin tried to link to <tt><path to>/ExternalPrograms/repository/lib/<some library></tt> instead of the bundle library (or even worse to <tt>/opt/local/lib/<some library>, which means that you did not correctly [[Get MacPorts and/or Fink out of the way]].<br /> The <tt>Complete-bundle.sh</tt> script mentioned in [[Edit Complete-bundle.sh]] will alter the "hard linked" paths inside Hugin and inside the libraries to "internal" paths, using the [http://www.hmug.org/man/1/INSTALL_NAME_TOOL.php install_name_tool], to make sure that they can find each other inside the bundle. If this did not work correctly (one of the non-fatal errors for Xcode), your Hugin.app will not run on another system as it will still try to use the libraries inside your build environment. This build environment is not available on another "Xcode and Hugin free" Mac.<br />

If everything worked fine you really made a portable application. 




=='''Notes'''==
{{reflist}}


=='''External Links'''==
- What is [http://en.wikipedia.org/wiki/Endianness endianness].<br />
- MacPorts set endianness [http://guide.macports.org/#reference.variables read-only] for the platform it's installed on.

[[Category:Software:Hugin]] [[Category:Software:Platform:Mac OS X]]