arch/all-android/README.txt

   1  1. INTRODUCTION.
   2
   3  This is Google Android-hosted port of AROS. Android is a subset of Linux system, so many functionality
   4 of this port is the same as of a generic Linux-hosted port.
   5  Both ARM and i386 architectures are supported, however only ARM is tested.
   6
   7  A minimum required Android version is 2.2 (API level 8).
   8
   9  2. COMPILING.
  10
  11  In order to compile Android-hosted AROS you need:
  12
  13  - A usual prerequisites for building AROS (GNU/UNIX-compatible environment). If you are running Windows, MinGW
  14    (MSYS) is the recommended one. Cygwin is much slower, and it will unlikely work with Android NDK because gcc
  15    versions supplied with modern Android NDK are MinGW-hosted, not Cygwin. Don't be confused by the fact that
  16    NDK's own build system is claimed to require Cygwin. AROS doesn't use this build system, it uses only gcc
  17    compiler, includes and link libraries from the NDK. NDK build system, when used, translates paths from UNIX
  18    to Windows style for the gcc; AROS build system won't do the same under Cygwin. If running Cygwin, it assumes
  19    all tools are Cygwin-hosted. It's possible to build Android-targetted gcc for Cygwin, but this was never tested.
  20    At the moment Cygwin is generally deprecated for building AROS, and Cygwin-related portions in the configure
  21    script are poorly maintained.
  22
  23    One note: MinGW project does not offer netpbm package on their web site. It can be found in another project,
  24    GNUWin32. GNUWin32 ports perfectly cooperate with MinGW ones.
  25
  26  - ARM AROS-targeted crosscompiler. At the moment only MacOS X/x86-64 version can be found on AROS Archives
  27    as binary distribution. You have to build own AROS toolchain if running another system. The process is
  28    straightforward and explained in README files for gcc and collect-aros. Please feel free to release your
  29    built toolchains on AROS Archives in order to assist other developers.
  30
  31    Note that Android-targetted gcc can't be used for building AROS binaries even with wrapper scripts.
  32    Android ABI is not 100% compatible to AROS one.
  33
  34  - Android SDK (Java one). The new build was succesfully tested with SDK r10 on MacOS X v10.6.8 (x86-64).
  35    During early development stages SDK v1.6r1 was used under Windows. In fact any SDK version should work.
  36
  37  - Android NDK (Native Development Kit). Versions statring from r5 are known to be supported. Earlier versions
  38    are not expected to work, because directory tree structure was changed.
  39    Android NDK has an option to generate a "standalone" version of Android toolchain. For AROS this is options.
  40    AROS build system is expected to support such toolchains, but this was not tested.
  41
  42  - Apache Ant or Eclipse. These are optional, however without them you won't be able to build Java application
  43    containing the bootstrap. For automated builds (e. g. nightly build) Ant is mandatory.
  44
  45  Configure script needs the following additional parameters to set up Android-hosted build:
  46
  47  --target=linux-<cpu>            - Android is a subset of Linux architecture
  48
  49  --enable-target-variant=android - This actually tells to set up Android-hosted build
  50
  51  --with-sdk=<path>               - Specifies location of installed Android SDK. This parameter currently can't be
  52                                    omitted at all. There is some default for it, however it is unlikely to fit
  53                                    your machine, since the SDK does not suggest any specific default location by
  54                                    itself.
  55
  56  --with-ndk=<path>               - Specifies location of installed Android NDK. If you omit this, AROS build system
  57                                    will expect to use standalone toolchain installed in your $PATH.
  58
  59  --with-gcc-version=<number>     - If you are not using a standalone Android toolchain generated from the NDK,
  60                                    you must specify it. Otherwise AROS won't be able to locate a gcc inside it.
  61                                    NDKs r5 and r6 are both supplied with version 4.4.3. If this ever changes,
  62                                    you can easily check which gcc version is contained in your NDK. Just look
  63                                    into "toolchains" subdirectory.
  64
  65  --with-sdk-version=<number>     - The value of this parameter is Android API level number (not OS version).
  66                                    It specifies platform version to use within the SDK. Current minimum SDK API
  67                                    level is 12. Please don't confuse it with minimum API version required to
  68                                    run AROS, these are different. Java code uses some methods declared only
  69                                    starting from v12 API, however it works correctly if they are missing. High
  70                                    SDK version is required just to compile this code.
  71                                    You can easily look up what platform versions are supported by your SDK by
  72                                    examining its 'platforms' subdirectory.
  73
  74  --with-ndk-version=<number>     - Similar to --with-sdk-version, but specifies API level for the NDK. This is
  75                                    different from SDK because: a) SDK doesn't include all levels included in the
  76                                    NDK; and b) AROS display driver needs some includes from API level 9 (despite
  77                                    AROS runs on level 8). This parameters defaults to 9 and will be needed if
  78                                    older API levels are dropped from the NDK at some point.
  79
  80  Android documentation says that APKs must be signed in order for the system to allow installing them.
  81 AROS build system is set up to sign the built application with "AROS" key located in $HOME/.android/AROS.keystore.
  82 If you are setting up the build for the first time, you need to create this key. In order to do this you need
  83 to use "keytool" utility supplied with the JDK:
  84
  85  keytool -genkey -keystore ~/.android/AROS.keystore -alias AROS -validity 366000
  86
  87  Unfortunately, a certificate must have validity period. In this example we set it to more than 1000 years
  88 (for simplicity we count every year for 366 days). The longer the time, the better. AROS is not going to die! :)
  89
  90  After this command keytool will ask for your personal data. It's recommented to fill them in correctly, this can
  91 help to identify origins of the build. When the keytool asks you for key password, use 'aros.org'. This password
  92 is specified in build.properties file of the Java project, this allows ant to operate fully automatically and
  93 not to ask you for the password every time. This is especially useful for automated (e. g. nightly) builds.
  94
  95  Remember that AROS is an open project! It doesn't honor any conspiracy. Everyone is allowed to make builds and
  96 publish them. This key exists only because Android mandates it. It's neither meant to be used for some private
  97 authentication, nor serves for enforcing some limitations on the end user. These are reasons why key password
  98 is stored open in the SVN tree. It's possible to adjust the build system to use arbitrary system-specific key
  99 and password, but this is not done for simplicity reasons.
 100
 101  3. INSTALLING.
 102
 103  In order to install AROS on your Android device, you need:
 104
 105  - Copy 'AROS' directory with all its contents to the root of your SD card (or whatever else external storage).
 106  - Instal AROSBootstrap.apk like any other application.
 107
 108  4. RUNNING.
 109
 110  There's nothing particular about this. Run 'AROS' application and enjoy.
 111  Note that AROS was initially developed as a desktop OS. Android-hosted port is the first completed port to run on
 112 mobile devices. Consequently, AROS lacks many features that could make it a mobile system. First of all, AROS lacks
 113 a virtual keyboard. Second, user interface is not optimized to be operated by fingers and/or keypad. If your device
 114 has a keyboard, AROS will support it, however this was not tested yet. 'Menu' key found on most of Android devices
 115 emulates right mouse button and 'Back' button emulates LAmiga+M sequence (screen switch).
 116
 117  For more comfortable use you can do the following:
 118
 119  - Turn on 'Sticky menus' option in IControl preferences.
 120  - Enable popup system menus.
 121  - Set larger fonts for user interface, to increaze size of controls.
 122
 123  Note that trackball found on NexusOne phone is of a very poor quality. It is supported by AROS as a mouse, however
 124 the cursor speed will be very slow, even if you turn on the acceleration. This is a property of the trackball itself
 125 and it can't be fixed by software. Android OS uses it to emulate keypad, not as a mouse. Perhaps AROS should do this
 126 too, this is subject to further development.
 127
 128  There is intentionally no support kludges that would make use of Android's own virtual keyboard. AROS is not an
 129 emulator, it's an operating system by itself, and it should contain own support for such things, independently
 130 on what it's running on. Remember that one day AROS will run natively on these devices. The same reason prevents
 131 AROS from supporting autorotating screen. AROS user interface libraries currently has no concept of screen rotation,
 132 and it's unclear how it can be implemented (however it's not impossible).
 133
 134  An intensive development is needed to remove these limitations.
 135
 136  However, it's actially possible to run AROS in both landscape and portrait orientation. Both orientations are available
 137 as different display modes in ScreenMode preferences program.
 138
 139  5. DEBUGGING.
 140
 141  For Java part AROS build system creates a complete Eclipse project. It's located in
 142 $(TOP)/bin/linux-$(CPU)-android/gen/arch/all-android/bootstrap/app. You can import it into Eclipse workspace and
 143 work with it as usually. On UNIX systems the project will contain symlinks to original directories, so files
 144 modified in Eclipse will stay in their original place. Unfortunately on Windows this is not possible, and directories
 145 will be copied instead (unless MinGW implements support for post-XP symlinks). So, if you modify something there,
 146 you'll have to copy your changes back to SVN tree. Theoretically it's possible to work around it by modifying Java
 147 build paths inside the project, i haven't tried it.
 148
 149  Debug output from AROS itself is copied to Android debug buffer. You can read it as usually, using 'logcat' command
 150 in Android shell. Also you can use 'logfile' option in AROSBootstrap.conf in order to save the output to a file, the
 151 same as in any other hosted port.
 152
 153  Androd NDK documentation describes a way to attach gdb to a process on the device. This was not tested with AROS,
 154 however is expected to work.
 155
 156  AROS is expected to run inside Android emulator, since it's full ARM machine emulator, not a hosted environment
 157 like for example iOS or Symbian simulators. I haven't tried it because of: a) complicated process of SD card image
 158 creation; and b) overall slowness of the emulator even on very fast computers. It was much faster and easier to use
 159 the real hardware for the development.
 160
 161  6. HACKING.
 162
 163  Android is a very hostile environment to a native code. All Android applications are running inside a Java VM.
 164 It uses UNIX signals for own purposes, conflicting with AROS multitasking. This makes it impossible to run AROS
 165 directly in application's context. It was proved during early port development. There's no way to shut down
 166 Java environment.
 167
 168  In order to work around this limitation, AROS runs in its own process asynchronously. Comminication with Android
 169 OS is implemented using client-server architecture. Before running AROS via fork(), bootstrap creates two pipes
 170 (see Kick() method implementation). These pipes are used as communication channels to and from display server,
 171 written in Java. AROS display driver sends action commands to the server, and gets input events from it. This is
 172 the only way for AROS to communicate with Android APIs other than Linux kernel and C libraries on top of it.
 173  It's unknown whether it's possible to call Android GL API from within AROS under this conditions.
 174
 175  Because of this, please, keep communication with Java at a minimum. In order to prevent from de-synchronization
 176 all commands are processed by display server in the same order as in which they arrived. In order to satisty this,
 177 Java display server thread forwards all commands to main user interface thread, where they are processed and
 178 replied. Such an architecture very negatively impacts on the overall AROS performance, especially when a command
 179 needs a reply, and it's a good practice to stay away from it. It's impossible to remove a separate display server
 180 thread because Java API lacks asynchronous I/O facilities which could be used together with Android user interface
 181 processing.
 182  Fortunately Android's lower layers (kernel and C libraries) do not suffer from any limitations, and at least basic
 183 system services (file access, time, signals, etc) can be freely used by AROS. If someone wants to try his hands on,
 184 for example, accelerometer support for AROS, the primary way to go would be direct interfacing with the device using
 185 /dev directory.
 186
 187  If you work with code using communication pipes, remember the general rule: pipe error on any side should cause
 188 immediate process exit. The pipe can be broken if one of processses exit. In this case, if the user interface exits,
 189 and AROS fails to notice this, you'll end up in blindly running AROS process without any control on it. It's impossible
 190 to even use kill command on non-rooted device, so the only way to get rid of such process (draining the battery and
 191 system resources) is to completely reboot the device. Please do everything possible to avoid this!
 192
 193  An alternate way to run hosted AROS on Android device would be total shutdown of Java environment and taking over
 194 the device. AROS would need a Linux framebuffer display and raw hardware input drivers. There is very old source code
 195 of these drivers which is slowly being reworked. The only drawback of such approach is that cellular phone will stop
 196 being serviced. AROS would need to take care of it itself then. Additionally, it would require a rooted device.
 197
 198                                                                         Pavel Fedin <pavel_fedin@mail.ru>