added: ticket #8540 - Enable visualizer when playing audio-only files via DVDPlayer...
[xbmc:xbmc-antiquated.git] / README.osx
1 TOC
2 1. Introduction
3 2. Getting the source code
4 3. Install required libs
5   3.1. Install Xcode
6   3.2. Install MacPorts 1.7
7 4. How to compile and run
8         4.1 Using XCode
9         4.2 Using Command line
10 5. Packaging
11
12 -----------------------------------------------------------------------------
13 1. Introduction
14 -----------------------------------------------------------------------------
15
16 This is a platform port of XBMC for the Apple OSX operating system. Both 10.5
17 and 10.4 Intel development platforms are supported. The current build system
18 is Xcode 2.5 or Xcode 3.1.2 There are two ways to build XBMC for Mac.
19 1) command-line or
20 2) Xcode.
21
22 Generally, Xcode is the easiest as it presents the build system in a GUI environment.
23 The command-line build is still under development.
24
25 XBMC for Mac is composed of a main binary with numerous dynamic libraries and
26 codecs that support a multitude of music and video formats.
27
28 NOTE TO NEW OS X USERS: All lines that are prefixed with the '$' character are
29 commands that need to be typed into a Terminal window. Note that the '$'
30 character itself should NOT be typed as part of the command.
31
32
33 -----------------------------------------------------------------------------
34 2. Getting the source code
35 -----------------------------------------------------------------------------
36
37  $ cd $HOME
38  $ svn checkout https://xbmc.svn.sourceforge.net/svnroot/xbmc/trunk
39
40 -----------------------------------------------------------------------------
41 3.0 Install XCODE
42 -----------------------------------------------------------------------------
43 Install latest Xcode. You can download it from Apple's site after registration at
44 (http://developer.apple.com/tools/download). You also need to install the 10.4
45 sdk. If using Xcode 3.x, you MUST use Xcode 3.1.2 so update your existing version
46 if you are running a previous Xcode 3.x version. Xcode 3.x only runs on 10.5.
47
48
49 -----------------------------------------------------------------------------
50 3.1 Install MacPorts 1.7
51 -----------------------------------------------------------------------------
52
53 These build instructions depend on MacPorts 1.7.1 from xbmc-port-depends. 
54 If you have another version of MacPorts installed, it's best to remove it and
55 install this 1.7.1 version. To remove a previous install of MacPorts, enter the
56 following from a terminal windows:
57
58  $ sudo rm -rf \
59     /opt/local \
60     /etc/manpaths.d/macports \
61     /etc/paths.d/macports \
62     /Applications/DarwinPorts \
63     /Applications/MacPorts \
64     /Library/LaunchDaemons/org.macports.* \
65     /Library/Receipts/DarwinPorts*.pkg \
66     /Library/Receipts/MacPorts*.pkg \
67     /Library/StartupItems/DarwinPortsStartup \
68     /Library/Tcl/darwinports1.0 \
69     /Library/Tcl/macports1.0
70
71 Install MacPorts 1.7.1 (see http://code.google.com/p/xbmc-port-depends/). No NOT
72 install the versions from http://www.macports.org, they were hopelessly broke
73 for XBMC usage when their devs released MacPorts 1.8. Change MacPorts's behavior
74 to always build universal against 10.4sdk using the following instructions.
75
76  1)
77    $ sudo nano /opt/local/etc/macports/macports.conf
78    a) change "universal_target  10.5" to "universal_target      10.4"
79
80    b) change "universal_sysroot /Developer/SDKs/MacOSX10.5.sdk" to
81      "universal_sysroot /Developer/SDKs/MacOSX10.4u.sdk"
82
83    c) change "universal_archs         ppc i386"
84      to reflect the arch you are building by removing the unused arch.
85
86  2) These are needed to build openssl (used by samba3 and mysql5) against 10.4sdk
87    $ sudo ln -s /Developer/SDKs/MacOSX10.4u.sdk/usr/lib/dylib1.o /Developer/SDKs/MacOSX10.4u.sdk/usr/lib/dylib1.10.5.o
88    $ sudo ln -s /Developer/SDKs/MacOSX10.4u.sdk/usr/lib/crt1.o /Developer/SDKs/MacOSX10.4u.sdk/usr/lib/crt1.10.5.o
89
90
91 Then install the following port packages (order is very important):
92
93  $ sudo port install pcre +universal
94  $ sudo port install expat +universal
95  $ sudo port install libiconv +universal
96  $ sudo port install gettext +universal
97  $ sudo port install libtool yasm cmake gmake pkgconfig
98
99  $ sudo port install lzo +universal
100  $ sudo port install lzo2 +universal
101  $ sudo port install bzip2 +universal
102  $ sudo port install fontconfig +universal
103  $ sudo port install boost +universal
104
105  $ sudo port install jpeg +universal
106  $ sudo port install tiff +universal
107  $ sudo port install libpng +universal
108  $ sudo port install libogg +universal
109  $ sudo port install libvorbis +universal
110  $ sudo port install libmad macosx_deployment_target=10.4
111  $ sudo port install fribidi +universal
112  $ sudo port install libmms +universal
113  $ sudo port install wavpack +universal
114  $ sudo port install libmpeg2 +no_sdl +no_x11 +universal
115
116  $ sudo port install glew +universal
117  $ sudo port install libcdio +universal
118  $ sudo port install openssl +universal
119  $ sudo port install samba3 macosx_deployment_target=10.4
120  $ sudo port install mysql5 +universal
121  $ sudo port install sqlite3 +universal
122  $ sudo port install libsamplerate +universal
123
124  $ sudo port install libsdl +no_x11 +universal
125  $ sudo port install smpeg +universal
126  $ sudo port install libsdl_mixer +universal
127  $ sudo port install libsdl_image +universal
128
129 If you understand the following two lines, you can run it to automate
130 the installation of the ports in the above order:
131
132   sudo bash
133   cat README.osx | perl -ne 'print `port install $1` if /^ \$ sudo port install (.*)$/;'
134
135 Finally, fix the mysql package default install location with this symlink:
136
137  $ sudo ln -s /opt/local/include/mysql5/mysql/ /opt/local/include/mysql
138
139 -----------------------------------------------------------------------------
140 4. How to compile
141 -----------------------------------------------------------------------------
142 Both Xcode and Terminal compilation require that build environment be setup
143 first. This is a simple step and involves the following:
144
145  $ cd $HOME/XBMC
146  $ ./bootstrap
147  $ ./configure
148  $ make clean
149  $ make xcode_depends
150
151 The configure operation will setup the build environment for codecs and
152 internal libraries that are used by XBMC. This step is required for both Xcode
153 and command-line building. The "make clean" ensures that there areno stale
154 binaries from svn that might cause problems The last step will pre-build
155 the majority of the codecs and libs:
156
157
158 The configure operation will default to building "debug". To build "release"
159 codecs and libraries for Xcode, do the configure step with "--disable-debug"
160 but remember that Xcode will need to be also built "Release":
161
162  $ ./configure --disable-debug
163
164 -----------------------------------------------------------------------------
165 4.1 Using Xcode
166 -----------------------------------------------------------------------------
167 Start XCode and open the XBMC project (XBMC.xcodeproj) located in $HOME/XBMC.
168 For development, XBMC is run from the $HOME/XBMC directory and needs to have
169 the XBMC_HOME environment variable set to know where that directory is located.
170 To set XBMC_HOME environment variable:
171
172 Menu -> Project -> Edit Active Executable "XBMC", click "Arguments" tab and
173 add "XBMC_HOME" as an enviroment variable. Set the value to the path to the
174 XBMC root folder. For example, "/Users/bigdog/Documents/XBMC"
175
176 There are two build targets "XBMC" and "XBMC.app" with debug and release
177 settings. The "XBMC" target is used for rapid build and debug cycles while
178 the "XBMC.app" target is used to build a self contained OSX application.
179
180 Set the build target to "XBMC" or "XBMC.app", then build. The build process
181 will take a long time when builting the first time. You can see the progress
182 in "Build Results". There are a large number of static and dynamic libaries
183 that will need to be built. Once these are built, subsequent builds will be
184 faster.
185
186 After the build, you can ether run XBMC for Mac from Xcode or run it from
187 the command-line. If you run it from the command-line, make sure your set
188 the XBMC_HOME environment variable (export XBMC_HOME=$HOME/XBMC). Then, to
189 run the debug version:
190
191 $ ./build/Debug/XBMC
192
193 Or the release version:
194
195 $ ./build/Release/XBMC
196
197 You can also build via Xcode from the command-line using the following:
198
199 $ xcodebuild -configuration Release -target "XBMC.app" -project XBMC.xcodeproj
200
201 You can specify "Release" instead of "Debug" as a configuration.
202
203 -----------------------------------------------------------------------------
204 4.2 Using Terminal (command-line) (this is a work in progress and might fail)
205 -----------------------------------------------------------------------------
206 There are two methods, a) make/Xcode and b) make (which might fail as it's under
207 construction).
208
209 If you want to build a cross-compiled version that can run under 10.5/10.4/AppleTV, 
210 then you'll need to follow the additional steps listed in $HOME/XBMC/tools/XBMCTex/README.osx
211 before running xcodebuild from the command-line.
212
213  a)
214  $ cd $HOME/XBMC
215  $ export XBMC_HOME=`pwd`
216  $ make xcode_depends
217  $ xcodebuild -sdk macosx10.4 -project XBMC.xcodeproj -target XBMC.app -configuration Release build
218
219  b)
220  $ cd $HOME/XBMC
221  $ export XBMC_HOME=`pwd`
222  $ make xbmc
223  $ ./xbmc.bin
224
225 -----------------------------------------------------------------------------
226 5. Packaging
227 -----------------------------------------------------------------------------
228 This section describes how to package XBMC in a disk image for
229 distribution.
230
231   1. Create 2 directories "extras/user" and "extras/system" in the root of
232   the source tree.
233
234     1.1. "extras/user" - anything found in this directory will be
235     copied to the users XBMC directory (~/Library/Application
236     Support/XBMC) on first run. Examples:
237
238         extras/user/scripts/XBMC Lyrics
239         extras/user/plugins/music/iTunes
240
241     1.2. "extras/system" - anything found in this directory will be
242     copied to the XBMC application bundle at build time
243     (XBMC.app/Contents/Resources/XBMC/). Examples:
244
245         extras/system/skin/MediaStream
246         extras/system/skin/My Skin
247
248
249   2. After performing step 1, build XBMC.app from XCode so that the
250   application bundle is correctly updated.
251
252   3. make -C tools/PackageMaker/
253
254   4. If completed successfully, a disk image named XBMC_for_Mac.dmg will be
255   present in the users XBMC build directory:
256
257 Remember to unmount/eject XBMC.dmg before attempting to recreate it,
258 otherwise dmgmaker.pl will fail.