Skip to content

Commit a95a9b9

Browse files
itsakyitsaky
committed
add 'Tutorials' section
1 parent 14df535 commit a95a9b9

File tree

9 files changed

+735
-0
lines changed

9 files changed

+735
-0
lines changed

‎docs/_static/images/screenshots/installation-alert-dialog.png

-149 KB
Binary file not shown.

‎docs/_static/images/screenshots/installation_setup_tools.png

173 KB
Loading

‎docs/index.rst

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,18 @@
33
AndroidIDE Documentation
44
========================
55

6+
.. toctree::
7+
:maxdepth: 1
8+
:glob:
9+
:hidden:
10+
:caption: 🚀 Tutorials
11+
12+
tutorials/get-started
13+
tutorials/manual-installation
14+
tutorials/build-first-project
15+
tutorials/signing-apks
16+
tutorials/using-room-db
17+
618
.. toctree::
719
:maxdepth: 2
820
:glob:

‎docs/tutorials/build-first-project.rst

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
.. _tutorial-build_first_project_in_androidide:
2+
3+
Build your first project with AndroidIDE
4+
========================================
5+
6+
This tutorial shows how to create and build your first project with AndroidIDE.
7+
8+
Before we start
9+
---------------
10+
11+
In this tutorial, we're going to walk through the steps required to build your first project with AndroidIDE.
12+
13+
Before we start, please make sure that you have installed the build tools required to build the projects. See this post
14+
about :doc:`setting up the build tools in AndroidIDE </tutorials/get-started>`.
15+
16+
If you have the build tools installed, you can proceed with the next steps.
17+
18+
Create a project
19+
----------------
20+
21+
For this tutorial, we're going to create a new project. However, you could choose an existing project or even clone a
22+
git repository.
23+
24+
Creating a new project is easy. Follow the steps to create a new project:
25+
26+
27+
* Open the AndroidIDE application and from the main screen, click on the ``Create project`` button.
28+
* You'll be asked to choose a project template. You can choose any template of your choice.
29+
* After you've chosen a project template, you'll be asked to enter the project details like the application name and its
30+
package name. Fill in the details and click on the ``Create project`` button to create the project.
31+
32+
That's it! Your project will be created and opened automatically for you.
33+
34+
Project synchronization
35+
-----------------------
36+
37+
After the IDE opens the project, it'll start the Gradle project synchronization. This is necessary for the IDE to get
38+
information about your project and its dependencies. This information is then used to provide you other services.
39+
40+
.. note::
41+
42+
If you’re building your first project in AndroidIDE, it'll take some time to download the Gradle distribution and
43+
other project dependencies. After that, only the required dependencies need to be downloaded.
44+
45+
Depending on your internet connection, **the first build may take up to 10-15 mins**. Please be patient and let it
46+
setup the project for you.
47+
48+
49+
While the project synchronization is in progress, you can swipe-open the bottom sheet to see the build output. The build
50+
output view shows the logs which are emitted by the Gradle Daemon while building your project. The first screenshot
51+
below shows the bottom sheet view in its half-expanded state while the second one shows a successful project
52+
configuration.
53+
54+
55+
.. raw:: html
56+
57+
<div class="grid grid-cols-2 gap-2 overflow-x-auto">
58+
<div class="flex flex-row items-start">
59+
<img
60+
src="/_static/images/screenshots/bottom-sheet.png"
61+
class="block mx-auto"
62+
width="250px"
63+
alt="Bottom Sheet: Half expanded"/>
64+
<img
65+
src="/_static/images/screenshots/build-output-config-success.png"
66+
class="block mx-auto"
67+
width="250px"
68+
alt="Build output"/>
69+
</div>
70+
</div>
71+
72+
73+
Build the project
74+
-----------------
75+
76+
Once the project has been synchronized successfully, you can start to build the project.
77+
The `\ ``Quick run`` </docs/editor/#options-menu>`_ button in the toolbar is used to assemble the debug variant of your
78+
application. It runs the ``assembleDebug`` task and lets you install the built APK.
79+
80+
When you click on the button, the IDE will start to build your project. You can open the build output view
81+
to see the build output.
82+
83+
Once the project is built successfully, you'll be prompted to install the application. On newer Android versions, you
84+
might need to grant the installation permission to AndroidIDE before you can install the APK. Once you do that and
85+
install the application, you can open the newly built application.
86+
87+
The first screenshot below shows the IDE asking if the user wants to open the newly built application while the second
88+
one is a screenshot of the built application.
89+
90+
91+
.. raw:: html
92+
93+
<div class="grid grid-cols-2 gap-2 overflow-x-auto">
94+
<div class="flex flex-row items-start">
95+
<img
96+
src="/_static/images/screenshots/launch-app-confirmation.png"
97+
class="block mx-auto"
98+
width="250px"
99+
alt="Launch application confirmation"/>
100+
<img
101+
src="/_static/images/screenshots/sample-app.png"
102+
class="block mx-auto"
103+
width="250px"
104+
alt="Sample application"/>
105+
</div>
106+
</div>
107+

‎docs/tutorials/get-started.rst

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
.. _tutorial-getting_started_with_androidide:
2+
3+
Getting started with AndroidIDE
4+
===============================
5+
6+
This tutorial walks through the process of installing the build tools like
7+
JDK, Android SDK, etc. in AndroidIDE.
8+
9+
.. _tutorial-getting_started_with_androidide-intro:
10+
11+
Introduction
12+
------------
13+
14+
AndroidIDE is a feature-rich Integrated Development Environment (IDE) for developing Gradle-based Android
15+
applications on Android devices. The IDE offers an impressive range of features, including Gradle support, a
16+
Termux-based terminal with necessary packages, advanced Java and XML code completions.
17+
18+
AndroidIDE is available for download from the `AndroidIDE website <https://androidide.com>`_ or
19+
from `GitHub releases <https://github.com/AndroidIDEOfficial/AndroidIDE/releases>`_.
20+
21+
In this tutorial, we're going to walk through the steps required to setup the AndroidIDE build tools on your device.
22+
23+
.. _tutorial-getting_started_with_androidide-minreq:
24+
25+
Minimum requirements
26+
--------------------
27+
28+
Before installing and using AndroidIDE, it is essential to ensure that your device meets the minimum requirements to run
29+
the application.
30+
31+
* Supported CPU - You must ensure that your device has a CPU architecture that is supported by AndroidIDE. The following
32+
CPU architecture is supported by AndroidIDE:
33+
34+
- ``arm64-v8a`` - 64-bit ARM.
35+
- ``armeabi-v7a`` - 32-bit ARM.
36+
- ``x86_64`` - 64-bit ``x86``.
37+
38+
* Enough **available** RAM - You will be working with the Gradle build system. Depending on the size of your project,
39+
you'll need enough **free RAM** so that the Gradle Daemon is not killed by the system. A minimum of **1.5GB - 2GB free
40+
RAM** is recommended.
41+
42+
* Enough storage space - A minimum of 4GB free storage space is required. You'll need enough space for various Gradle
43+
distributions and dependencies, according to your project configuration. After the basic setup, around 1GB of space is
44+
used by AndroidIDE (without any dependencies or distributions installed).
45+
46+
An internet connection is required for the initial setup. A **WiFi connection** is recommended.
47+
48+
.. _tutorial-getting_started_with_androidide-install:
49+
50+
Install AndroidIDE
51+
------------------
52+
53+
The first step is to install the latest AndroidIDE APK. You could download the APK from the following sources :
54+
55+
* `The AndroidIDE Website <https://androidide.com>`_
56+
* `GitHub Releases <https://github.com/AndroidIDEOfficial/AndroidIDE/releases>`_
57+
* `GitHub Actions <https://github.com/AndroidIDEOfficial/AndroidIDE/actions>`_ only if you're willing to try out the
58+
latest, **unstable** builds.
59+
* `F-Droid <https://f-droid.org/packages/com.itsaky.androidide/>`_
60+
61+
.. warning::
62+
F-Droid and GitHub builds are incompatible with each other! If you have already installed AndroidIDE from GitHub and if
63+
you try to install AndroidIDE from F-Droid, it won't be installed. Same goes for installing GitHub builds over F-Droid builds.
64+
65+
Please make sure that you download the files only from the **trusted** sources above. Installing it from unknown sources
66+
may pose a security risk to your device.
67+
68+
.. _tutorial-getting_started_with_androidide-basic_setup:
69+
70+
Basic setup
71+
-----------
72+
73+
Before getting started with building projects, you need to install the basic build tools which are necessary for the IDE
74+
to function properly.
75+
76+
When you open the application for the first time, you'll be presented with the onboarding screen which will guide you to installing
77+
AndroidIDE and ask you for the following permissions :
78+
79+
* **Storage** - Required to work with files on the File System.
80+
* **Install packages** - Required for installing apps built with AndroidIDE.
81+
* **Post Notifications** - For Android 13 and above, you need to grant the ``POST_NOTIFICATION`` permission. This will be
82+
used to show notifications on your device.
83+
84+
There are three methods to install AndroidIDE:
85+
86+
* Automated installation
87+
88+
- Configure your installation with the GUI. This simply executes the ``idesetup`` script in the terminal. Once the installation is
89+
complete, it will automatically navigate you to the home screen.
90+
91+
.. note::
92+
Automated installation option is only available in **v2.7.0-beta** and newer.
93+
94+
* Manual installation
95+
96+
- ``idesetup`` script - provides you various options to install the tools.
97+
See :ref:`installation with idesetup <tutorial-getting_started_with_androidide-install_with_idesetup>`.
98+
99+
- Fully manual - manually install the tools by yourself. Choose this if you have already downloaded the tools or if you want to install
100+
custom tools in AndroidIDE. This can also be beneficial if you frequently re-install AndroidIDE.
101+
:doc:`See the manual installation guide </tutorials/manual-installation>`.
102+
103+
After you have granted the permissions, you'll be navigated to `Setup tools` screen which you can use to configure the installation.
104+
For example, you can choose to install `JDK 21` instead of `JDK 17` which is installed by default.
105+
106+
The below images show the SDK installation GUI and the terminal activity respectively :
107+
108+
109+
.. raw:: html
110+
111+
<div class="grid grid-cols-2 gap-2 overflow-x-auto">
112+
<div class="flex flex-row items-start">
113+
<img
114+
src="/_static/images/screenshots/installation_setup_tools.png"
115+
class="block mx-auto"
116+
width="250px"
117+
alt="Setup tools screen"/>
118+
<img
119+
src="/_static/images/screenshots/terminal.png"
120+
class="block mx-auto"
121+
width="250px"
122+
alt="Terminal"/>
123+
</div>
124+
</div>
125+
126+
.. _tutorial-getting_started_with_androidide-install_with_idesetup:
127+
128+
Install the build tools with ``idesetup``
129+
-----------------------------------------
130+
131+
The AndroidIDE terminal includes the ``idesetup`` command which downloads and installs the required build tools for your
132+
device. It is a simple shell script which downloads the required files from
133+
the `androidide-tools <https://github.com/AndroidIDEOfficial/androidide-tools>`_ GitHub repo and extracts them at their
134+
proper location. It also installs the ``openjdk-17`` package.
135+
136+
There are various options available in the script which you can use to customize the installation. However, **the
137+
default settings are always recommened**. To see the list of available options, you could execute the ``idesetup -h``
138+
which should print an output similar to the following :
139+
140+
.. code-block::
141+
142+
AndroidIDE build tools installer
143+
This script helps you easily install build tools in AndroidIDE.
144+
145+
Usage:
146+
idesetup -s 33.0.1 -c -j 17
147+
This will install Android SDK 33.0.1 with command line tools and JDK 17.
148+
149+
Options :
150+
-i Set the installation directory. Defaults to $HOME.
151+
-s Android SDK version to download.
152+
-c Download Android SDK with command line tools.
153+
-j Choose whether to install JDK 17 or JDK 21.
154+
-m Manifest file URL. Defaults to 'manifest.json' in 'androidide-tools' GitHub repository.
155+
156+
For testing purposes:
157+
-a CPU architecture. Extracted using 'uname -m' by default.
158+
-p Package manager. Defaults to 'pkg'.
159+
-l Name of curl package that will be installed before starting installation process. Defaults to 'libcurl'.
160+
161+
-h Prints this message.
162+
163+
In case you get an error saying ``bash: idesetup: command not found``\ , you could manually download and install the script
164+
with the following command :
165+
166+
.. code-block::
167+
168+
wget https://raw.githubusercontent.com/AndroidIDEOfficial/androidide-tools/main/scripts/idesetup -O $SYSROOT/bin/idesetup && chmod +x $SYSROOT/bin/idesetup
169+
170+
Now, **execute the following command** to start the build tools installation.
171+
172+
.. code-block::
173+
174+
idesetup -c
175+
176+
Once you execute the command, it'll print a summary of the configuration which you need to confirm. **Type ``y`` and press
177+
Enter** to confirm the configuration. The script will then start the installation procedure.
178+
179+
.. code-block::
180+
181+
------------------------------------------
182+
Installation directory : /data/data/com.itsaky.androidide/files/home
183+
SDK version : 33.0.3
184+
JDK version : 17
185+
With command line tools : true
186+
------------------------------------------
187+
Confirm configuration ([y]es/n[o]): y
188+
189+
The installation process may pause after some time and ask you for your confirmation about installing JDK 17. Just
190+
type ``y`` and press enter.
191+
192+
The first screenshot below shows the terminal screen where the installation process is in progress and the second one
193+
shows the screen where installation process has been completed.
194+
195+
196+
.. raw:: html
197+
198+
<div class="grid grid-cols-2 gap-2 overflow-x-auto">
199+
<div class="flex flex-row items-start">
200+
<img
201+
src="/_static/images/screenshots/installation-in-progress.png"
202+
class="block mx-auto"
203+
width="250px"
204+
alt="Installation in progress"/>
205+
<img
206+
src="/_static/images/screenshots/installation-completed.png"
207+
class="block mx-auto"
208+
width="250px"
209+
alt="Installation completed"/>
210+
</div>
211+
</div>
212+
213+
214+
Once the installation is completed, you can verify the installation by checking the Java version with ``java --version``
215+
command. Your output must be similar to :
216+
217+
.. code-block::
218+
219+
openjdk version "17-internal" 2021-09-14
220+
OpenJDK Runtime Environment (build 17-internal+0-adhoc.root.src)
221+
OpenJDK 64-Bit Server VM (build 17-internal+0-adhoc.root.src, mixed mode)
222+
223+
It is recommended to restart AndroidIDE after the installation.
224+
225+
Congratulations! You've successfully installed the build tools in AndroidIDE. Now it's time
226+
to ::doc:`build your first project </tutorials/build-first-project>`.

0 commit comments

Comments
 (0)