Fixed: Also check for the day prior to the epoch to account for timezone issues when...
[xbmc:xbmc-antiquated.git] / README.armel
1 TOC
2 1. Introduction
3 2. Using Scratchbox
4         2.1 Automatic Installation
5         2.2 Manual Installation
6         2.3 Installation Continued for both Automatic and Manual Methods
7         2.4 Setup Scratchbox
8 3. Getting the source code
9 4. Installing the required ARMEL packages
10 5. Obtaining the SGX files
11 6. How to compile
12         6.1 Configure & Make
13         6.2 Install
14 7. How to run
15         7.1 Obtaining the Packages
16         7.2 Installing the Files
17         7.3 Running XBMC
18 8. Troubleshooting
19
20
21 -----------------------------------------------------------------------------
22 1. Introduction
23 -----------------------------------------------------------------------------
24
25 This is a port of XBMC for use on ARM Architecture.
26 As this is not an official version of XBMC, in-depth testing on various setups has not been done. USE WITH CAUTION!
27 For the purpose of this port, the following Hardware and Software was used.
28 Software: Scratchbox (cross-compiler) on a Linux (Ubuntu) machine.
29 Hardware: BeagleBoard (ARM Cortex-A8 with IMG POWERVR SGX).
30 The source code is based on XBMC for Linux - version 9.11 (Camelot).
31
32 All lines that are prefixed with the '$' character are commands that need to be typed into a standard linux terminal
33 All lines that are prefixed with the '>' character are commands that need to be typed into scratchbox
34 All lines that are prefixed with the '#' character are commands that need to be typed into a terminal on the beagleboard
35
36
37 -----------------------------------------------------------------------------
38 2. Using Scratchbox
39 -----------------------------------------------------------------------------
40
41 First, you need scratch box, along with some other packages.
42 The easiest way is to do the following automatic installation.
43 If you dont succeed, or want to do it manually, follow the next step instead.
44
45         -----------------------------------------------------------------------------
46         2.1 Automatic Installation:
47         -----------------------------------------------------------------------------
48
49                 $ sudo gedit /etc/apt/sources.list
50                 
51         Add this to the end of the file, then save and exit gedit:
52                 deb http://scratchbox.org/debian stable main
53                 deb http://scratchbox.org/debian legacy main
54                 
55         Now enter the following command:
56                 $ sudo apt-get install scratchbox-core scratchbox-libs scratchbox-devkit-cputransp scratchbox-devkit-git scratchbox-devkit-mtd scratchbox-devkit-perl scratchbox-devkit-doctools scratchbox-toolchain-arm-linux-cs2007q3-51sb3 scratchbox-toolchain-host-gcc scratchbox-devkit-debian
57
58         -----------------------------------------------------------------------------
59         2.2 Manual Installation:
60         -----------------------------------------------------------------------------
61
62         Go to the following website:
63                 http://www.scratchbox.org/download/files/sbox-releases/stable/tarball/
64         and download the following files (Unless specified, choose latest version):
65         - core
66         - libs
67         - cputransp
68         - doctools
69         - git
70         - mtd
71         - perl
72         - toolchain (cs2007q3-51sb3)
73         - host-gcc
74         - debian
75
76         To install
77                 $ cd /
78                 $ sudo tar xvf /<location of files>/scratchbox-core.tar.gz
79
80         Repeat for all the downloaded files.
81
82         -----------------------------------------------------------------------------
83         2.3 Installation Continued for both Automatic and Manual Methods:
84         -----------------------------------------------------------------------------
85
86         Now, a few changes needs to me made in order for it to work correctly:
87                 $ sudo gedit /etc/sysctl.conf
88                 
89         Change/Add these variables:
90                 vm.mmap_min_addr = 4096
91         vm.vdso_enabled = 0
92         Save and Close.
93
94         Add yourself to scratchbox:
95                 $ sb-adduser <username>
96                 
97         Make sure it worked by doing the following command, and see if sbox is listed.
98                 $ groups
99
100         If it isnt listed, restart and try again. If it still isnt listed, then do the following:
101                 $ usermod -a -G sbox <username>
102                 
103         It should now list (possibly after another logout)
104         Now you have access to scratchbox.
105         
106         -----------------------------------------------------------------------------
107         2.4 Setup Scratchbox:
108         -----------------------------------------------------------------------------
109         
110         Before setting up your target, you need a rootstrap. Obtain the latest rootstrap from:
111                 http://linux.onarm.com/download/images/generic-X/
112         You want to download the file 'beagleboard-<date>-rootstrap.tar.gz'.
113
114         Do this every time you want to access scratchbox:
115                 $ /scratchbox/login
116         
117         Time to setup your target:
118                 > sb-menu
119         
120         A GUI will appear for the setup procedure.
121             - Choose Setup
122             - Create a NEW target, give it any name
123             - Select the compiler you downloaded (arm-linux-cs2007q3-51sb3)
124             - Select all development kits listed by highlighting each one and pressing enter, then Done and enter
125             - Select CPU transparency (qemu-arm-cvs-m)
126             - Yes to rootstrap. Locate the previously downloaded rootstrap to install.
127             - Yes to install files
128             - Only select DEVKIT and ETC. Remove all other files in list, then continue
129             - And finally Yes to selecting target.
130
131         Now scratchbox is setup
132
133         
134 -----------------------------------------------------------------------------
135 3. Getting the source code
136 -----------------------------------------------------------------------------
137
138    $ sudo apt-get install subversion
139    $ cd /scratchbox/users/<username>/home/<username>/
140    $ svn checkout https://xbmc.svn.sourceforge.net/svnroot/xbmc/branches/xbmc_on_arm
141
142    
143 -----------------------------------------------------------------------------
144 4. Installing the required ARMEL packages
145 -----------------------------------------------------------------------------
146
147 There is a simple shell script that downloads a list of packages that are required and installs them into scratchbox.
148
149   > cd tools/arm/arm-scripts/
150   > ./install-pkgs.sh
151   
152 Please check the output files for any possible errors that may have occured.
153
154 Note. You will need the headers and shared object files for EGL and GLESv2 to continue.
155
156
157 -----------------------------------------------------------------------------
158 5. Obtaining the SGX files
159 -----------------------------------------------------------------------------
160
161 In order to continue, you will need the SGX SDK from TI's website.
162 Once you have installed said SDK on a standard Linux machine, copy the neccessary .h and .so files to the appropriate directories in scratchbox:
163 e.g /scratchbox/users/<username>/targets/<target_name>/usr/include/EGL/egl.h
164 These files will also need to be transferred over to the board eventually.
165 NOTE: XBMC has only been tested with the following versions of the OMAP35x Graphics SDK:
166 3.00.00.05, 3.00.00.06, 3.00.00.08, 3.00.00.09
167
168
169 -----------------------------------------------------------------------------
170 6. How to compile
171 -----------------------------------------------------------------------------
172
173 To create the XBMC executable manually perform these following steps:
174
175         -----------------------------------------------------------------------------
176         6.1 Configure & Make:
177         -----------------------------------------------------------------------------
178         
179         $ ./bootstrap
180             > ./configure --enable-gles
181
182     This will configure XBMC inside scratchbox ready for compilation on ARM.
183     Because the default is to build for OpenGL, we require the --enable-gles flag to be set for OpenGL ES 2.0.
184     (Note: No OpenGL ES 1.x available)
185         Now, build with the following:
186         
187                 > make
188         
189         -----------------------------------------------------------------------------
190         6.2 Install:
191         -----------------------------------------------------------------------------
192
193         There is no need to do 'make install' as we dont want it installed into scratchbox.
194         There is also the slight problem of the fact that scratchbox's 'find' command is outdated and wont execute xbmc's 'make install' correctly.
195         Instead, use the provided shell script:
196                 > cd /tools/arm/arm-scripts/
197                 > ./create-xbmcfile.sh
198                 
199         This will create a tar file tools/arm/arm-scripts/xbmc.tar.bz2 containing the xbmc files, ready for you to transfer to the board.
200
201
202 -----------------------------------------------------------------------------
203 7. How to run
204 -----------------------------------------------------------------------------
205
206 It is assumed you have a beagleboard with all the neccessary hardware installed.
207 (e.g keyboard, mouse, and ethernet adapter)
208 It is also assumed that you have it setup with either Angstrom or Ubuntu.
209
210         -----------------------------------------------------------------------------
211         7.1 Obtaining the Packages:
212         -----------------------------------------------------------------------------
213
214         For Ubuntu: See README.linux for list of packages to install.
215         If planning on not extracting the pkgs file, a few additional packages are required to be installed.
216         These are python and liblzo2
217
218         For Angstrom:
219                 # opkg update
220                 # opkg install subversion make g++ gcc gawk pmount libtool automake gperf unzip bison libsdl-1.2-dev libsdl-image-1.2-dev libsdl-gfx-dev libsdl-mixer-1.2-dev libfribidi-dev liblzo-dev libfreetype-dev libsqlite3-dev libasound2 python-sqlite3 libcurl4 libxrandr-dev libxrender-dev libmad-dev libogg-dev libvorbis-dev libmysqlclient-dev libpcre-dev libdbus-glib-1-dev hal-dev libjasper-dev libfontconfig-dev boost-dev libxt-dev libxmu-dev libpng-dev libjpeg-dev libsamplerate0-dev
221         
222         Unfortunately this will only install the packages that are available through opkg. There will be further packages that need to be installed.
223         Either use the method mentioned below, or selectively find and install packages, mentioned at the bottom of this README.
224
225         Alternatively, do the following:
226         First make sure you have done section 4. then do the following:
227                 > cd xbmc_on_arm/arm-scripts/
228                 > ./create-pkgsfile.sh
229
230         This will create a tar file xbmc_on_arm/arm-scripts/pkgs.tar.bz2 containing the packages, ready for you to transfer to the board.
231
232         -----------------------------------------------------------------------------
233         7.2 Installing the Files:
234         -----------------------------------------------------------------------------
235
236         Transfer the file(s), armel-pkgs.tar.bz2 (if using alternative method mentioned above) and xbmc.tar.bz2 to the beagleboard.
237         Do the following to extract them:
238                 # tar xjf armel-pkgs.tar.bz2 -C /
239                 # tar xjf xbmc.tar.bz2 -C /usr/
240
241         After this initial setup, during development, you should only need to replace /usr/share/xbmc/xbmc.bin with the newly created binary.
242         
243         -----------------------------------------------------------------------------
244         7.3 Running XBMC:
245         -----------------------------------------------------------------------------
246
247         Now, run XBMC by executing the binary:
248                 # /usr/share/xbmc/xbmc.bin
249                 
250         Run the binary and not the script as the script will fail.
251         
252         
253 -----------------------------------------------------------------------------
254 8. Troubleshooting
255 -----------------------------------------------------------------------------
256         
257 If it fails to run correctly, there are a few things to try out.
258 First, is there any helpful output on the terminal?
259 Check the log file, usually located ~/.xbmc/temp/xbmc.log
260 It may have failed because of a missing package.
261 If so, you will need to download the appropriate armel package from packages.debian.org,
262 Extract the files with the command: dpkg-deb -x packagename.deb /path/to/extract/to
263 Then tarball the extracted files: tar cjf pkg.tar.bz2 /path/to/extracted/files
264 Then transfer them to the board, and extract: tar xjf pkg.tar.bz2
265 This is because the .deb files cannot be extracted in Angstrom.
266
267 If this is not the case, try various different parameters for xbmc.bin such as:
268 xbmc.bin --standalone
269 xbmc.bin -p
270 xbmc.bin -fs
271 Or build with debug for a more in-depth xbmc.log file by ommitting the line --disable-debug on configure.
272
273 Feel free to contact me on mcgeagh@xbmc.org