Building AAPS

בנייה עצמית במקום הורדה

The AAPS app (an apk file) is not available for download, due to regulations around medical devices. בנייה עצמית של היישום לשימוש אישי הינה חוקית אך אסור לתת את היישום לאחרים!

See FAQ page for details.

Computer and software specifications for building AAPS

OS (Only 64 bit) Windows 8 or higher Mac OS 10.14 or higher Any Linux supports Gnome, KDE, or Unity DE;  GNU C Library 2.31 or later

CPU (Only 64 bit)

x86_64 CPU architecture; 2nd generation Intel Core or newer, or AMD CPU with support for a
Windows Hypervisor
ARM-based chips, or 2nd generation Intel Core or newer with support for
Hypervisor.Framework
x86_64 CPU architecture; 2nd generation Intel Core or newer, or AMD processor with support for AMD Virtualization (AMD-V) and SSSE3

RAM

8GB or more

Disk

At least 30GB free space. SSD is recommended.

Resolution

1280 x 800 Minimum

Internet

Broadband

It is strongly recommended (not mandatory) to use SSD (Solid State Disk) instead of HDD (Hard Disk Drive) because it will take less time when you are building the AAPS apk file. You can still use a HDD when you are building the AAPS apk file. If you do, the building process may take a long time to complete, but once it has started, you can leave it running unattended.

Help and support during the building process

If you run into difficulties in the process of building the AAPS app, there is a dedicated troubleshooting Android Studio section, please consult that first.

If you think something in the building instructions is wrong, missing or confusing, or you are still struggling, please reach out to other AAPS users group on Facebook or Discord. If you want to change something yourself (updating screenshots etc), please submit a pull request (PR).

Step-by-step guide to building the AAPS app

WARNING

If you have built AAPS before, you don’t need to take all the following steps again. Please jump directly to the update guide!

In this guide you will find example screenshots of building of AAPS apk file. Because Android Studio - the software which we use to build the AAPS apk - is regularly updated, these screenshots may not be identical to your installation, but they should still be possible to follow.

Since Android Studio runs on Windows, Mac OS X and Linux platforms, there might be also be minor differences in the steps for the different platforms.

Install Git

Steps for Installing Git

  1. Check that you don’t already have Git installed. You can do this by typing “git” in the Windows search bar – if you see “Git bash” or some other form of Git, it is already installed and you can go straight to installing Android Studio:

Git_installed

  1. If you don’t have Git installed, download and install the latest version for your system from the ”Download“ section on here. Any recent Git version should work, select the correct version according to your system, either Mac, Windows and Linux.

Note for Mac users: the Git webpage will also guide you to install an additional program called ”homebrew“ to aid the installation. If you install Git via homebrew, there is no need to change any preferences.

  • During the installation, when you are asked to ”select destination location“ make a note of where Git is being installed (the ”installation path“) you will need to check it in the next step. It will be something similar to ”C:\Program Files\Git\cmd\git.exe“

  • As you proceed through several steps of the Git installation, just accept all the default options.

  • After the install, if you forgot to make a note of the where Git was installed, you can find it as follows: type ”git“ into the PC search bar, right click on ”Git bash“, select ”open file location“ hover over the ”Git bash“ icon with your mouse, which will then reveal where it is installed.

  • Reboot your computer before the next step.

התקנת Android Studio

  • You have to be online all of the time during the following steps, as Android Studio downloads several updates

One of the most important things when installing Android Studio is be patient! During installation and setup, Android Studio is downloading a lot of stuff which will take time.

Any version of Android Studio like version Hedgehog or any newer is suitable. With version Ladybug, you might need to do one extra step, but it’s doable!

Different UI

Import note: Android Studio changed its UI during the last releases. This guide will show you the steps with the new UI in ”Ladybug“. If you still use the older UI, you might want to change Android Studio to the new UI first following these instructions.

Download the current version of Android Studio or an older version from the Archives and accept the download agreements.

DownloadAndroidStudio

Once the download is finished, start the downloaded application to install it on your computer. You might need to accept/confirm some warnings about downloaded apps from Windows!

Install Android Studio by clicking ”Next“, as shown in the following screenshots. You do not need to change any settings!

Welcome_to_Android_Studio_Setup

Choose_components

Configuration_Settings

Now click on ”Install“:

Choose_start_Menu_Folder

Once it’s completed, press ”Next“

Installation_Complete

In the last step, click on ”Finished“ to start Android Studio for the first time.

Completing_Android_Studio_Setup

You will be asked if you want to help improve Android Studio. Choose the option to your liking, it won’t make any difference for the following steps.

Help_improve_Android_Studio

The welcome screen greets you to the installation of Android Studio. Press ”Next“.

Welcome

Select ”Standard“ as installation type.

Install_Type

Verify the settings by clicking ”Next“ again.

Verify_Settings

Now you need to accept the license agreements. You have two sections (1 + 3) on the left side which you have to select one after the other and each select ”Accept“ (2 + 4) on the right side.

Then the ”Finish“ (5) button can be clicked.

License_Agreement

Some Android packages will now be downloaded and installed. Be patient and wait.

When it’s finished, you will find the following screen where you can select ”Finish“ again.

Downloading_Components

You will now see the Welcome screen of Android Studio.

Welcome_to_Android_Studio

Download the AAPS code

On the Android Studio Welcome screen, check that ”Projects“ (1) is highlighted on the left.

Then click ”Get from VCS“ (2) on the right:

Get_from_VCS

We will now tell Android Studio where to get the code from:

Get from Version Control

  • ”Repository URL“ should be selected (by default) on the left (1).

  • ”Git“ should be selected (by default) as version control (2).

  • Now copy this URL:

    https://github.com/nightscout/AndroidAPS.git
    

    and paste it into the URL textbox (3).

  • Check the (default) directory for saving the cloned code exists on your computer and doesn’t already exists (4). You can change it to some directory, but please remember where you stored it!

  • Now click the button ”Clone“ (5).

INFORMATION

Make a note of the directory. It is where your sourcecode is stored!

You will now see a screen telling you that the repository is being cloned:

cloning_repository

At some point, Android Studio will close and start again. You may be asked whether you want to trust the project. Click on ”Trust project“:

Trust project

Only for Windows users: If your firewall asks for permission, grant access:

Firewall permission java

After the repository is cloned successfully, Android Studio will open the cloned project.

New UI

Android Studio changed its UI recently. New installations of Android Studio use the new UI by default!

Only if your Android Studio looks different, you might need to switch to the new UI: Click on the hamburger menu on the top left, then select Settings (or Preferences on Apple computers). In Appearance & Behaviour, go to New UI and tick Enable new UI. Then restart Android Studio to start using it.

If you don’t find the option New UI don’t worry: you are already using it!

When Android Studio opened, wait patiently (this may take a few minutes), and particularly, do not update the project as suggested in the pop-up.

Android Studio will start a ”Gradle project sync“ automatically, which will take a couple of minutes to finish. You can see it (still) running:

AS_download_dependencies

NEVER UPDATE GRADLE!

Android Studio might recommend updating the gradle system. Never update gradle! This will lead to difficulties.

Only on windows computers: You might get a notification about windows defender running: Click on Automatically and confirm, it will make the build run faster!

Windows Defender

You can leave the gradle sync running and follow the next steps already.

Set Git path in Android Studio preferences

Now we will tell Android studio where to find Git, which you installed earlier.

  • Windows users only: Make sure you have restarted your computer after installing Git. If not, restart now and re-open Android Studio

In the top left corner of Android Studio, open the hamburger menu and navigate to File > Settings (on Windows) or Android Studio > Preferences (on Mac). This opens the following window, click to expand the dropdown called Version Control (1) and select Git

Version_control_Git

Check if Android Studio can automatically locate the correct Path to Git executable automatically by clicking the button ”Test“ (1):

Git Executable

If the automatic setting is successful, your current version of Git will be displayed next to the path.

Git_version_displayed

If you find that git.exe is not found automatically, or that clicking ”Test“ results in an error (1), you can either

  • manually enter the path which you saved earlier, or

  • click on the folder icon (1) and manually navigating to the directory where git.exe was installed earlier

  • Verify your settings with the Test button!

    Git not found

Build the AAPS ”signed“ APK

Important: Make sure the gradle sync is finished successfully before proceeding!

Click the hamburger menu on the top left to open the menu bar. Select Build (1), then select Generate Signed App Bundle / APK (2)

Build apk

Select ”APK“ instead of ”Android App Bundle“ and click ”Next“:

APK instead of bundle

In the next screen, make sure that ”Module“ is set to ”AAPS.app“ (1).

INFORMATION!

If you want to create the apk for your watch, you now need to select AAPS.wear!

Create_key_store

Click ”Create new…“ (2) to start creating your key store.

INFORMATION!

You will only need to create the keystore once. If you have build AAPS before, do NOT create a new keystore but select your existing one and enter its passwords!

Note: The key store is a file in which the information for signing the app is stored. It is encrypted, and the information is secured with passwords.

Create key store

  • Click the ”folder“ symbol (1) to select a path on your computer for your key store.

    Do not use the directory where you stored your sourcecode but some directory that you would also transfer to a new computer.

WARNING!

Make sure to note down for yourself where your keystore is stored. You will need it when you build the next AndroidAPS update!

  • Now choose a simple password (and make a note of it), enter it in the password box (2), and confirm it (2).

    The passwords for key store and key do not have to be sophisticated. If you lose your password in the future, see troubleshooting for lost key store.

  • The default alias (3) for your key is ”key0“, leave this unchanged.

  • You now need a password for your key. To keep it simple, if you want, you can use the same password you used for your keystore, above. Enter a password (4) and confirm it.

WARNING!

Note down these passwords! You will need them when you build the next AAPS update!

  • The validity is 25 years by default, leave it as it is.

  • Enter your first and last name (5). No other information needs to be added but you are free to do (6-7).

  • Click ”OK“ (8) to continue:

On the Generate signed App Bundle or APK page, the path to your keystore will now be displayed. Now re-enter the Key Store password (1) and Key password (2), and tick the box (3) to remember passwords, so you don’t have to enter them again next time you build the apk (i.e. when updating to a new AAPS version). Click ”Next“ (4):

Remember passwords

On the next screen, select build variant ”fullRelease“ (2) and click ”Create“ (3). You should remember the directory displayed at (1), as later you will find your built apk file there!

Select build variant

Android Studio will now build the AAPS apk. It will show ”Gradle Build running“ (2) at the bottom right. The process takes some time, depending on your computer and internet connection, so be patient! If you want to watch the progress of the build, click on the small hammer ”build“ (1) at the bottom of Android Studio:

Gradle Running

Now you can watch the building progress:

Android_Studio_building

Android Studio will display the information ”BUILD SUCCESSFUL“ after build is finished. You may see a popup notification which you can click to select ”locate“. If you miss this, click on the notification icon (1) and then on locate (2) at the very bottom of the screen to bring up the Notifications:

Build finished

If the build was not successful, refer to the Android Studio Troubleshooting section.

In the Notifications box, click on the blue link ”locate“:

Locate build Your file manager will open and show you the build apk file that you have just built.

File location apk

מזל טוב! Now you have built the AAPS apk file, you will be transferring this file to your smartphone in the next section of the docs.

טיפ

If you think you might want to use an Android Wear smartwatch in the future, this is the best time to build the AAPS Wear apk to be sure it will be synchronized with your AAPS apk.

Move to the next stage of Transferring and Installing AAPS.