KT Doc-Hub

Appearance

Mobile App Development ​

All Platforms ​

Building xcode workspace and android studio projects inside container for debugging. ​

For building an app for testing and production, we use the device-app-builder. Which has actions for building and creating app bundles(eg. android APK). However, sometimes we want to debug the app from their project files(in either xcode or android studio).

This can help:

  • Test plugin code for an app that runs natively using the platform specific debuggers
  • Debug a production app when usually a production app bundle will not let you. See here
  • Test an app on a previous os version. See here

Requirements

  • Xcode(for iOS)
  • Android Studio
  • Docker or Docker Desktop(on Mac)

Steps ​

bash

git clone git@github.com:kaarbontech/device-app-builder.git

If you want to debug the app for iOS and Android on your local machine, you will need to setup the device-app-builder docker image on your local machine.

  • Build the docker image using the build_builder.sh script

Run the script from the root of the device-app-builder repo.

./manual_scripts/build_builder.sh

This script builds an image and tags it kt-app-builder-local

IMPORTANT

The script also handles building the image for platforms linux/amd64(matching the github action arch) on apple silicon devices using rosetta.

  • Checkout drains repo into root of device-app-builder

We need the drains code to build the app inside the container. Clone from https://github.com/kaarbontech/drains so the drains folder is in the root of the device-app-builder repo

with:

bash
git clone git@github.com:kaarbontech/drains.git

Your directory structure should now look like this, with the drains folder in the root of the device-app-builder folder

├── device-app-builder
│   ├── Dockerfile
│   ├── README.md
│   ├── docs
│   ├── drains
...
  • Run kt-app-builder-local image, mounting the drains repo checked out in the previous step as a volume

From the device-app-builder root folder run:

bash
docker run -d --name buildcontainer -v ./drains:/ktech/drains kt-app-builder-local bash -c "tail -f /dev/null"
  • Open a shell session in the running container

Using:

bash
docker exec -it buildcontainer /bin/bash
  • Use npm to install deps inside the buildcontainer image

Using:

bash
cd /ktech/drains
npm run installdeps

IMPORTANT

installdeps needs to be run inside the container, as some build tool packages have binaries specific to the environment. So if you run installdeps on your host, it will install binaries that cannot be ran inside the container

WARNING

There is an issue with using npm and pnpm hoisting in a container running on Apple Silicon hosts. See The Need for package-import-method=clone-or-copy in .npmrc when using docker build image on mac.

  • Build app inside container

Change into the app builder directory from the /ktech/drains directory.

bash
cd tools/app-builder

Set environment variables KT_APP and PLATFORM(ios or android) for your app you want to build.

eg.

bash
export KT_APP=WokingTree-test
export PLATFORM=ios

Run npm run debug to build the app projects without bundling them.

NOTE

Usually the device-app-builder would run npm run build to build apps, this also creates the bundles for android but causes problems debugging the app in android studio. So run npm run debug if you plan on debugging the app.

  • Open the generated platform app in either Xcode(ios) or Android Studio(android)

On your host machine, open the device-app-builder/drains/tools/app-builder folder

You should find a newly generated folder called ${KT_APP}-gen. Inside that folder there will be a platforms folder, which should either contain an xcode project, or an android studio project.

For Xcode, open the .xcworkspace file to open the project in xcode.

For Android Studio. Open the platforms/android folder as the android project.

Webview debugging a live build ​

All live cordova builds do not allow attaching a webview debugging instance(either through chrome on android or safari on ios). You shouldn't need to debug a live app, as a test app should be enough. However if there is a need to debug a production app, there is a work around if you run the app from their built projects. Either in xcode or android studio.

You can use either simulated or real devices and attach a web debugger.

NOTE

To debug an app on iOS on a real device, you will need to use a Developer Profile and make sure your device is listed on that profile.

Usage of inject tool for updating javascript with an android studio project or xcode workspace ​

When debugging changes to your app, tou can rebuild the entire project again using npm run debug as mentioned above.

However this runs all the steps to build the native libraries and plugins. If you just want to update the JS bundles quickly, a utility in the app-builder called inject can update the js bundle in an exiting built project.

See the Inject tool README for more information.

The Need for package-import-method=clone-or-copy in .npmrc when using docker build image on mac. ​

One downside of building an app in a docker container when your drains repo code is mounted as a volume on your host machine. pnpm has some issues hoisting and creating symlinks. This is a common issue when using a build image on a Mac(namely apple silicone) due to the rosetta arch translation.

To stop pnpm from hoisting you can set the package import method to clone-or-copy by creating a .npmrc file at the root of the drains repo.

In the container: /ktech/drains/.npmrc

package-import-method=clone-or-copy

Creating simulators for older runtimes for debugging ​

It might be useful to test a bug on a previous runtime, for example iOS 16. When your test device has been updated to iOS 17.

In Xcode for iOS ​

  • In xcode under the Window menu, go to "Devices and Simulators"
  • Click on the Simulators tab next to Devices
  • Click the plus icon at the bottom left of the window to add a new simulated device
  • Here you can pick a device type(eg. iPad 7th Generation) and a previous os version runtime. Note you may have to download a os version if you don't have it installed already, and it can be a large file to download. So it might take some time.
  • You can now use this simulated device to run app in.

In Android Studio ​

  • In Android Studio under the Tools menu, go to "Device Manager"
  • At the top of the list click the plus icon to Create a new Virtual Device
  • Pick a tablet device and click next to select an image
  • Android Studio will recommend a recent image, go to the tab "other images" to find older android versions for your virtual device.