Building the Kotlin app
This is a document which details how to build the Readium Kotlin test-app. It is assumed that the reader does not have Android Studio (AS) or the r2-kotlin-app sources, though it does assume that the user is familiar with git and github.
Go to the Android Studio homepage here, and download the latest AS (currently 3.1.4 in August 2018). Run the installer on your system and let it install with the preset defaults.
Once installed, start AS. What gets installed initially is more than a stub, not the complete development tools and all the dependencies. When AS starts up it checks to ensure its installation and libraries are up-to-date. Almost always, they are not. However, AS needs to know what is being built in order to properly update, so the next step is in fact to clone the r2-kotlin-app (e.g. git clone https://github.com/readium/r2-testapp-kotlin.git).
Then open AS and open the Kotlin project. Opening the project is not immediately intuitive if you haven't used AS before. Instead of a project file or similar, one does File/Open/... and then navigate to the folder where you cloned the repo (above, i.e. \<sandbox\>/r2-test-app-kotlin). AS will see that the folder contains the gradle files and other resources needed by AS. AS will open the folder and files and proceed to try and build the project.
When the project has finished loading and building you should see the project as:
The next step is to run the project and validate that it all works correctly. You have two choices in how to run the project - an actual Android device (e.g. a Nexus 7 etc.). Alternatively, you can create a virtual device.
Need info on setting up a real device here
The first step is to create the virtual device. Android Studio supports a very broad range of devices. To create a virtual device, select Tools/AVD Manager/... This will bring up a window like:
AS will populate the dialog with a couple of defaults (MyAVD and Nexus, in this example). You also can see that (on my MacOS) I had already created on virtual device, the Pixel XL. But let's create a new one. In the dialog, choose the "Tablet" tab. Then select "Nexus 7" in the tablet pane:
Then choose "Next" and you will be presented with a dialog prompting you to choose a version of Android.
In this case, select "Oreo - Android 8.1") and press "Next". BUt wait! Nothing happens. Note the little message in the lower right "A system image must be selected to continue". Note that next to the "Oreo" label in the second row is a hyperlink of "Download". This is because AS doesn't come with that system image installed so you need to install it by clicking on the link. Go ahead and do so and a new dialog will come up "Installing Requested Components". THere's a lot to downd load and install so this will take a few minutes. Eventually, you should see this dialog:
Press "Finish" to complete the process and dismiss the dialog. That will return you to the previous (AVD Manager) dialog. You should see:
Review the settings to check that they look OK. Note the "Advanced..." button which gives you access to some other parameters including the amount of memory allocated for the device, its SD card, etc. Press "Finish" to complete the process and dismiss the dialog.
Now back in the main window of AS, click on Run/Run r2-testapp-kotlin. This will bring up the AVD Manager again, with the Nexus 7 as one of the choices. Choose the Nexus 7 and let it run. The first time you launch the virtual device it will take a little while to start so be patient. With luck, the Kotlin app will come up on your screen:
[Note, this screen-shot is flawed - apparent bug in the Android emulator for the Nexus 7]