deliver-to-android-project Function

Summary

Deliver LispWorks for Android. Implemented only in LispWorks for Android Runtime.

Package

hcl

Signature

deliver-to-android-project function project-path level &key library-name no-sub-dir studio-p &allow-other-keys

Arguments

Description

The function deliver-to-android-project delivers a LispWorks runtime for the Android platform.

deliver-to-android-project creates two files, a Lisp heap and a dynamic library. It does some processing that is specific to delivering for Android, including producing the dynamic library, and then calls deliver to produce the Lisp heap. The two files are specific to the architecture of the image in which the call happens. The architecture can be 32-bit or 64-bit ARM, which correspond to the armeabi-v7a or arm64-v8a Android ABIs respectively, or 32-bit or 64-bit x86, which correspond to x86 and x86_64 respectively. Thus to deliver an Android project for multiple ABIs, you need to deliver using deliver-to-android-project in each architecture. See 16.1.1 Configuration for Separate APKs for different architectures for discussion.

To actually use the Lisp code, the Lisp heap and dynamic library need to be included in your APK and the application's Java code needs to call com.lispworks.Manager.init. See the description of project-path below, together with no-sub-dir and studio-p, for details about how the files can be included in your APK.

library-name defaults to "LispWorks", and when supplied must be a string. It defines the base name of the files that deliver-to-android-project produces, and much match the name that you supply as the deliverName argument in the call to the Java method com.lispworks.Manager.init (which also defaults to "LispWorks").

The dynamic library file that deliver-to-android-project generates is named liblibrary-name.so. The heap file is named liblibrary-name.so.armeabiv7a.lwheap for the 32-bit ARM architecture, liblibrary-name.so.arm64v8a.lwheap for the 64-bit ARM architecture, liblibrary-name.so.x86.lwheap for the x86 architecture or liblibrary-name.so.x86_64.lwheap for the x86_64 architecture. Thus the default names are libLispWorks.so and either libLispWorks.so.armeabiv7a.lwheap, libLispWork.so.arm64v8a.lwheap, libLispWork.so.x86.lwheap, or libLispWork.so.x86_64.lwheap. com.lispworks.Manager.init assumes this naming scheme based on its deliverName argument, so if you rename the files after delivery then you need to change the deliverName argument.

function can be nil, in which case it is ignored. If function is non-nil it is a restart function that is called after the LispWorks runtime finishes initializing. It is called asynchronously with no arguments (by mp:funcall-async) and its return value is not used. By the time function is called, LispWorks is ready to receive calls from Java, and a call from function to Java may be used to inform Java that LispWorks is ready, as an alternative to using the reporter argument to com.lispworks.Manager.init (or in parallel to it). function should return in a short time (because it is called by mp:funcall-async), so it should call mp:process-run-function to start another process if it might take a long time.

level is the delivery level. It is passed to deliver. See the documentation for deliver for details.

After deliver-to-android-project has determined the names of the files and where they go (see Determining the location to write the files), it prepares the image for running on Android and generates the dynamic library. It then calls deliver, passing function, the appropriate path, level, the deliver keywords :split, :exe-file, :dll-exports and :image-type with the correct values for Android, and all the keyword arguments it was supplied with except library-name, studio-p and no-sub-dir. The keywords that deliver-to-android-project passes explicitly should not be used, but the rest of the deliver keywords can be used and are interpreted in the standard way (see the Delivery User Guide for details). However, since CAPI is not available on Android, all keywords related to CAPI are not useful.

Description: Determining the location to write the files

no-sub-dir defaults to nil, and studio-p default to (not no-sub-dir). If studio-p is non-nil, then deliver-to-android-project deduces a "source set" directory (as described below). This directory is assumed to be a "source set" directory as used by Android Studio, and the files are placed in directories below it where Android Studio expects them to be. The dynamic library file is put in a sub-sub-directory named according to the architecture in which deliver-to-android-project is called: jniLibs/armeabi-v7a for ARM 32-bit, jniLibs/arm64-v8a for ARM 64-bit, jniLibs/x86 for x86 32-bit or jniLibs/x86_64 for x86 64-bit. The heap file is placed in a sub-directory named assets. If studio-p is nil, both files are placed directly in the directory that is deduced by project-path and no-sub-dir.

If no-sub-dir is nil (the default), then deliver-to-android-project deduces the "source set" directory using the first step that matches from the following steps:

1. If the directory specified by project-path contains a file named AndroidManifest.xml, then project-path is the "source set" directory.
2. If there is a file named AndroidManifest.xml in the path app/src/main/ relative to project-path, then project-path/app is taken as the "module directory", and the "source set" directory is deduced inside it as described in the next step.
3. If there is a file named AndroidManifest.xml in the path src/main/ relative to project-path, then project-path is assumed to be the "module directory".

   deliver-to-android-project then checks if there is an "architecture specific source set directory" relative to the "module directory". The "architecture specific source set directory" is expected to be src/archspecific, where archspecific is specific to the architecture in which deliver-to-android-project is called: armeabiv7a for ARM 32-bit, arm64v8a for ARM 64-bit, x86 for x86 32-bit and x86_64 for x86 64-bit (Note that the ARM names contain no hyphens, unlike the corresponding Android ABI names). If such a directory exists, then this is the "source set" directory to put the files in, otherwise the standard location src/main/ under the "module directory" is the "source set" directory.

   Note that armeabiv7a, arm64v8a, x86 and x86_64 are not standard Android Studio directories. The intention of this feature is that you have APK flavors with these names, and Android Studio uses these directories as extra "source set" directories. See 16.1.2 ABI splitting using flavors in the OthelloDemo for example how this is intended to be used.

4. If project-path has a sub-directory with a named archspecific (described in the previous step), then this sub-directory is the "source set" directory. Note that in this case, it does not check for the existence of AndroidManifest.xml. This case is intended to allow you to use the same project-path for all architectures even when saving in a directory that is not inside the directory tree of the Android Studio project.
5. If deliver-to-android-project does not find any "source set" by matching any of the steps above, it signals an error. Thus to place the files in an arbitrary place you need to supply a non-nil value for no-sub-dir.

If no-sub-dir is non-nil, then project-path specifies the directory. Note that in this case, studio-p defaults to nil, so if you pass :no-sub-dir t and want to place the files in the appropriate directories as described above you need to also pass :studio-p t. If no-sub-dir is a string or a pathname, it specifies a directory which is merged using merge-pathnames with project-path as the defaults argument to specify where the Lisp heap file is to be written. This allows you to put the two files in two arbitrary and unrelated directories.

Notes

1. Prior to LispWorks 8.0, the default placing of the files in deliver-to-android-project was like in an Eclipse project. From LispWorks 8 onwards, the default matches an Android Studio project and deliver-to-android-project has features to make it simple to deliver ARM 32-bit, ARM 64-bit, x86 32-bit and x86 64-bit separately in order to create separate APKs for the two Android ARM ABIs (armeabi-v7a and arm64-v8a) and when using the x86 Android Emulator. See 16.1.2 ABI splitting using flavors in the OthelloDemo for an example of how the Android Studio project is intended to be configured for it to work. For a directory structure different from Android Studio's, use no-sub-dir to put the files in the correct places. In addition, the using-ndk argument has been removed because it was only useful for Eclipse projects.
2. Like deliver, deliver-to-android-project cannot be called with multiprocessing running, and is best called inside a script that is passed to LispWorks by the -build command line argument.
3. deliver-to-android-project is available only in the Android delivery images (lispworks-8-0-0-arm-linux-android, lispworks-8-0-0-arm64-linux-android, lispworks-8-0-0-x86-linux-android and lispworks-8-0-0-amd64-linux-android). These images must be run either on Linux with the corresponding architecture or using an emulator such as QEMU.

   You can use the shell script examples/android/run-lw-android.sh to deliver a LispWorks for Android Runtime image with a delivery script that calls deliver-to-android-project using the QEMU emulator:

   run-lw-android.sh -build /path/to/delivery-script.lisp
   

   Note that this script tries to deliver both 32-bit and 64-bit for ARM and x86 architectures on the host machine architecture when possible. It assumes that you have installed LispWorks for Android in your home directory, and that you are running on an ARM machine or have QEMU installed in your home directory. You may need to edit the script if these assumptions are incorrect.

See also

16 Android interface
Delivery User Guide