poco/doc/99300-AndroidPlatformNotes.page

POCO C++ Libraries Android Platform Notes
AAAIntroduction

!!!Introduction

Starting with release 1.4.2 the POCO C++ Libraries can be used on 
Android, using the NDK r6. The gmake-based build system (also used
for Mac OS X, Linux, etc.) is used to build the libraries.
A standalone "customized" toolchain for Android (see below) is required.


!!!Requirements

!!Standalone Toolchain

Please refer to the Android NDK Dev Guide document "Standalone Toolchain", section 3,
(<*docs/STANDALONE-TOOLCHAIN.html*>) for instructions how to create a customized toolchain.

Typically, you'll run a command like:

    $NDK/build/tools/make-standalone-toolchain.sh --platform=android-8 --install-dir=$HOME/my-android-toolchain
----

Then, add the directory containing the toolchain executables to your <[$PATH]>:

    export PATH=$PATH:$HOME/my-android-toolchain/bin
----


!!Compiling the POCO C++ Libraries

When compiling the POCO C++ Libraries for a Android target, as well as
when including POCO C++ Libraries headers in a project for a Android
target, the preprocessor macro <[POCO_ANDROID]> must be defined. This is
because the Android NDK GCC compiler does not provide a predefined macro that
allows for reliable detection of an Android target. 


!!!Restrictions

For the most part, the Linux and Android ports of the POCO C++ Libraries are very similar.
However, there are a few restrictions due to the Binoic C library used by Android.

!!Poco::NamedEvent and Poco::NamedMutex

These classes are not supported on Android. While Poco::NamedEvent and 
Poco::NamedMutex objects can be created, any attempt to call a method
of these classes will result in a Poco::NotImplementedException being thrown.

!!Poco::SharedMemory

Shared memory is not supported on Android.  

!!Poco::FPEnvironment

The Poco::FPEnvironment class is not available on Android and
cannot be used.    
    
!!Poco::RWLock

On Android, Poco::RWLock is an ordinary mutex.


!!!Build Notes

!!Using POCO's GNU Make-based Build System

The <*Android*> build configuration (located in <*$POCO_BASE/build/config/Android*>) 
is used to cross-build for Android from a Linux or Mac OS X host.

To build the POCO C++ Libraries (static) on a Linux or Mac OS X host:

    ./configure --config=Android --no-samples --no-tests
    ./make -s -j4
----

The default configuration builds for the <*armeabi*> platform ABI. To build for
<*armeabi-v7a*>, set the <[ANDROID_ABI]> make variable to <[armeabi-v7a]>:

    ./make -s -j4 ANDROID_ABI=armeabi-v7a
----

The build configuration also supports setting the <[ANDROID_ABI]> to <[x86]>,
but the NDK r6 standalone toolchain for x86 generated by <*make-standalone-toolchain.sh*>
lacks the C++ STL headers, so this does not work.

Depending on your specific requirements (e.g., no ARM architecture, etc.), it may be necessary
to modify the Android build configuration, or create a new one based on it.

See the [[99150-GMakeBuildNotes.html GNU Make Build System]] document for more information.


!!Using Android's Build System

Alternatively to POCO's build system, Android's build system can be used to build the
POCO C++ Libraries. A sample makefile for the Foundation library is shown below.

    #
    # Android.mk
    #
    # POCO Foundation
    #
    
    include $(CLEAR_VARS)
    
    LOCAL_MODULE     := PocoFoundation
    LOCAL_PATH       := $(call my-dir)/src
    LOCAL_CFLAGS     := -DPOCO_ANDROID -DPOCO_NO_FPENVIRONMENT -DPOCO_NO_WSTRING -DPOCO_NO_SHAREDMEMORY
    LOCAL_CPPFLAGS   := -frtti -fexceptions
    LOCAL_C_INCLUDES := $(call my-dir)/include
    
    LOCAL_SRC_FILES := \
        AbstractObserver.cpp \
        ActiveDispatcher.cpp \
        adler32.c \
        ArchiveStrategy.cpp \
        Ascii.cpp \
        ASCIIEncoding.cpp \
        AsyncChannel.cpp \
        AtomicCounter.cpp \
        Base64Decoder.cpp \
        Base64Encoder.cpp \
        BinaryReader.cpp \
        BinaryWriter.cpp \
        Bugcheck.cpp \
        ByteOrder.cpp \
        Channel.cpp \
        Checksum.cpp \
        compress.c \
        Condition.cpp \
        Configurable.cpp \
        ConsoleChannel.cpp \
        CountingStream.cpp \
        crc32.c \
        DateTime.cpp \
        DateTimeFormat.cpp \
        DateTimeFormatter.cpp \
        DateTimeParser.cpp \
        Debugger.cpp \
        deflate.c \
        DeflatingStream.cpp \
        DigestEngine.cpp \
        DigestStream.cpp \
        DirectoryIterator.cpp \
        DynamicAny.cpp \
        DynamicAnyHolder.cpp \
        Environment.cpp \
        ErrorHandler.cpp \
        Event.cpp \
        EventArgs.cpp \
        Exception.cpp \
        File.cpp \
        FileChannel.cpp \
        FileStream.cpp \
        FileStreamFactory.cpp \
        Format.cpp \
        Formatter.cpp \
        FormattingChannel.cpp \
        FPEnvironment.cpp \
        Glob.cpp \
        gzio.c \
        Hash.cpp \
        HashStatistic.cpp \
        HexBinaryDecoder.cpp \
        HexBinaryEncoder.cpp \
        infback.c \
        inffast.c \
        inflate.c \
        InflatingStream.cpp \
        inftrees.c \
        Latin1Encoding.cpp \
        Latin9Encoding.cpp \
        LineEndingConverter.cpp \
        LocalDateTime.cpp \
        LogFile.cpp \
        Logger.cpp \
        LoggingFactory.cpp \
        LoggingRegistry.cpp \
        LogStream.cpp \
        Manifest.cpp \
        MD2Engine.cpp \
        MD4Engine.cpp \
        MD5Engine.cpp \
        MemoryPool.cpp \
        MemoryStream.cpp \
        Message.cpp \
        Mutex.cpp \
        NestedDiagnosticContext.cpp \
        Notification.cpp \
        NotificationCenter.cpp \
        NotificationQueue.cpp \
        NullChannel.cpp \
        NullStream.cpp \
        NumberFormatter.cpp \
        NumberParser.cpp \
        Path.cpp \
        PatternFormatter.cpp \
        pcre_chartables.c \
        pcre_compile.c \
        pcre_exec.c \
        pcre_fullinfo.c \
        pcre_globals.c \
        pcre_maketables.c \
        pcre_newline.c \
        pcre_ord2utf8.c \
        pcre_study.c \
        pcre_tables.c \
        pcre_try_flipped.c \
        pcre_ucd.c \
        pcre_valid_utf8.c \
        pcre_xclass.c \
        Pipe.cpp \
        PipeImpl.cpp \
        PipeStream.cpp \
        PriorityNotificationQueue.cpp \
        Process.cpp \
        PurgeStrategy.cpp \
        Random.cpp \
        RandomStream.cpp \
        RefCountedObject.cpp \
        RegularExpression.cpp \
        RotateStrategy.cpp \
        Runnable.cpp \
        RWLock.cpp \
        Semaphore.cpp \
        SHA1Engine.cpp \
        SharedLibrary.cpp \
        SharedMemory.cpp \
        SignalHandler.cpp \
        SimpleFileChannel.cpp \
        SplitterChannel.cpp \
        Stopwatch.cpp \
        StreamChannel.cpp \
        StreamConverter.cpp \
        StreamCopier.cpp \
        StreamTokenizer.cpp \
        String.cpp \
        StringTokenizer.cpp \
        SynchronizedObject.cpp \
        SyslogChannel.cpp \
        Task.cpp \
        TaskManager.cpp \
        TaskNotification.cpp \
        TeeStream.cpp \
        TemporaryFile.cpp \
        TextBufferIterator.cpp \
        TextConverter.cpp \
        TextEncoding.cpp \
        TextIterator.cpp \
        Thread.cpp \
        ThreadLocal.cpp \
        ThreadPool.cpp \
        ThreadTarget.cpp \
        TimedNotificationQueue.cpp \
        Timer.cpp \
        Timespan.cpp \
        Timestamp.cpp \
        Timezone.cpp \
        Token.cpp \
        trees.c \
        UnicodeConverter.cpp \
        Unicode.cpp \
        URI.cpp \
        URIStreamFactory.cpp \
        URIStreamOpener.cpp \
        UTF8Encoding.cpp \
        UTF8String.cpp \
        UTF16Encoding.cpp \
        UUID.cpp \
        UUIDGenerator.cpp \
        Void.cpp \
        Windows1252Encoding.cpp \
        zutil.c
    
    include $(BUILD_STATIC_LIBRARY)
----