[Android Software/Hacking General [Developers Only]] amarullz:
Customizing AROMA Installer

Best Practice to learn about Customizing AROMA Installer was read and edit the aroma-config and updater-script directly from downloaded files, or for the completed features (but not well documented) was read aroma-config and updater-script from RunnyMede AIO,

Download RunnyMede AIO AROMA Installer Scripts!

And Some Interesting Answered Questions from TweetyPeety by me Here​

Customizing Your Script

AROMA Installer can be configured and customized as you like, there is so many features and functions you can used to implemented many things. In this manual, we will learn all the features and functions in technical ways and can be implemented directly in configuration for practice, or production.​

AROMA Installer Zip Directory Structures

AROMA Installer use standard ClockWorkMod zip Installer structures. All configurations will be placed in META-INF Folder in zip contents. Here the example directory structure for AROMA Installer:

All AROMA Installer files, should be placed in META-INF/com/google/android/. There is

2 Binary files

, and

2 Script/configuration files

, and

1 resources folder

.

aroma – Aroma Assets/Resource folder, It contains custom files, like png fonts, png icons, png splash images, text file for changelogs or agreement/license.

aroma-config – It was main AROMA Installer configuration script. This configuration was the one that supported AROMA Installer functions like Wizard UI's, Installer UI, Dialog UI, get and set variables, etc. This script wrote on Edify Script Sintax (See next chapter). This script not supported functions to manipulate system files/extract files and other installing method. It's only configuration to prepared all needed data for updater-script.

update-binary – It was AROMA Installer Executable, the compiled program wrote by me in C, and it was the program that show User Interface.

update-binary-installer – It was old update-binary (renamed to update-binary-installer), will be runs on Installer UI when the installer need to flash/install/extract files from zip to the phone.

updater-script – It was old edify format to start copying/install/extract files from zip to the phone. It will only support old functions that supported by update-binary-installer, but can read prop files created by AROMA Installer.

AROMA Installer Assets Directory

AROMA Installer use others files to show the interfaces, The Interfaces like windows, dialog, title, rounded rectangle and simple drawing was implemented by executable used compositing colors configurations, but for others drawing like text and icons, AROMA Installer will read zip contents in this asset directory.

The minimum requirements in this assets directory was png fonts files (big and small). It placed in fonts directory, an Icons can be placed in any directory of aroma assets, but for cleaner locations, it recommended to placed all icons in icons directory, And there is some default icons like alert.png, install.png and info.png that should be placed in this directory, because the installer executable was hardcoded icons locations like icons/alert.png for confirmation, icons/install.png for about dialog.

All splash and text files can be placed in anywhere but inside this assets directory. Example when you want to read text file into variable, use:

setvar("changelogs",readfile_aroma("changelogs.txt"));

It will find META-INF/com/google/android/aroma/changelogs.txt.​

Link Between aroma-config and updater-script

It was main section to be knowing by anyone that how can the aroma-config communicated with updater-script, so please read it carefully.

​

aroma-config and updater-script runs in different process, and can't share it's memory resource, so the only possible way to communicate is with temporary files. updater-script was original updater-script commonly used in old installer (without AROMA Installer), it's only supported bunch of functions to be used for manipulating system files, like delete_recursive, set_perm, format, mount, package_extract_dir, etc. But it's also support 1 function for read prop file, it was file_getprop.

That's why the AROMA Installer UI always save the result in prop files ( checkbox, optionbox, menubox ). Other than the UI, aroma-config has the feature to create temporary file in plain text (writetmpfile) which able easily create prop files.
​

Prop File Format

The prop file format was simple plain text format with (=) token as delimiter between key and values, and newline as delimiter between one key=values with another key=values.

key1=value1
key2=value2
key_3=value3
last.name=amarullz

It can be easily accessed with file_getprop in updater-script like this:

file_getprop("example.prop","key1");

With above code, the file_getprop function will return the value of key1, it will returned "value1". We can use it for our needs in if/if else statement. We can use others characters in keys, like dot (.) and underscore, but please be careful, that you don't add some quotes in the values. Here the wrong prop file format:

key1="value1" [COLOR="Red"]# add quotes[/COLOR]
key2="value2" [COLOR="Red"]# add quotes[/COLOR]
first name=james [COLOR="Red"]# Key name with space[/COLOR]

AROMA Installer Default Prop Temporary Locations

When playing with AROMA Installer aroma-config files, almost all things that manipulated prop files will be saved relatively on AROMA temporary directory located in /tmp/aroma-data/, so if we pass the prop filename like this: writetmpfile("test.prop","key1=ok");, the test.prop will be located at /tmp/aroma-data/test.prop.

Quick Example

In this example case, the aroma-config will create temporary prop file that will be readed by updater-script:

aroma-config:

writetmpfile(
"kernel.prop",
"snq =yes\n"+
"call.2way=no\n"
);

updater-script:

if
file_getprop("/tmp/aroma-data/kernel.prop","snq") == "yes"
then
# Install Kernel
write_raw_image("/tmp/boot.img", "boot");
endif;

if
file_getprop("/tmp/aroma-data/kernel.prop","call.2way") == "yes"
then
# Do Something here
else
# Do Something here
endif;

With this feature, it's enough to archive customizable installation, and the aroma-config will be able to communicate with updater-script.
​

EDIFY SCRIPT

Edify Script was simple script sintax to configure the behavior of binaries executable. In AROMA Installer, there is 2 edify script in the META-INF/com/google/android folder. The aroma-config and updater-script. Both files has it own use, and accessed by different binary executable, but use the same sintax, It's called edify.

The aroma-config used to configuring the UI in AROMA Installer, it will accessed directly by AROMA Binary Executable ( update-binary ), and updater-script will be used to configuring commands for installations (extract files, create symlinks, change permissions, format, mount, etc), and will be accessed directly by update-binary-installer. This couple script use the same sintax but have different functions that can be used.
​

Basic Edify Sintax

Edify Script was function base script, similar to C language, but without any supported statement except if else. You also can't create function, only bundled functions available for the script. All commands will call functions name with some arguments, and ends by semicolon, like this:

function_name( argument1, argument2, argument3 );

Edify also supporting simple concat-ing string, just like some other languages like Javascript or Java. Using plus (+).

function_name("Concat this " + "Strings" + " as one argument");

All Edify function's arguments was in type string. Edify doesn't support others data type, however, we can insert some integer values into arguments, but it in the fact it will be treated as string.

function_name( 50, 20, "55" );

We can't do any math calculation in edify script, so the script below is invalid:

function_name( 50 + 50 );

If you use the string with plus operator, it will only concat the strings just like the 2nd example:

function_name( "50" + "50" ); [COLOR="Green"]# Result = "5050"[/COLOR]

For commenting the code, we can use the sign character (#), only line comment was supported, just like an unix shell comment sintax:

[B]# This is comments[/B]
function_name("Lorem ipsum dolore…");

Code writing isn't strict, so we can safely use space or new line between function and arguments:

function_name(
"First Argument",
getvar("config"),
"Third Argument"
);

The functions in Edify Script can returned values. But just like an arguments, it's only supported string type data. The good thing is this String can be converted into Boolean for conditions need. The string with contents will have true Boolean, and the empty string will have false Boolean.

"" = false

"1" = true

"yes" = true

"no" = true

"0" = true

Control Structures

Edify only supported limited control structure. Only if, and if else supported. But this control structures is enough to make an interactive installer. The basic sintax of if structure is:

if
"comparison"=="comparison"
then
.. commands ..
endif;

And for if else structure is:

if
"comparison"=="comparison"
then
.. true commands ..
else
.. false commands ..
endif;

We don't have any looping control structure, the Next and Back features in Wizard UI was handled by program automatically.
​

Comparison & Logical Operators

Edify script doesn't supporting arithmetic operators, but it supported simple comparison and logical operators, Just like other programming languages base on C (java, php, javascript). It use simple operator sintax:

# Equal
val1 == val2

# Not Equal
val1 != val2

# Or
val1 || val2

# And
val1 && val2

# Not
!val1

# Logical & Comparison
(val1 == val2)||(val3 != val4)

(val1 == val2)&&(val3 != val4)

!((val1 == val2)&&(val3 != val4))

Yes, it doesn't support less than and greater than comparison, because it's only supported with string and Boolean string only. For Integer comparison use cmp function, but it's

only supported in aroma-config

script.
​

String and Escape Characters

Fortunately Edify support common string sintax. It's also supported escape characters for newline. The string in Edify defined with double quoted (") and ended with double quoted. Here the basic manipulation of string in Edify:

# Newline use \n:
"Hi, AROMA Installer is\nAWSOME!!!"

# Concat multiple lines:
"Lorem Ipsum Dolore sit\n"+
"Amet, lorem ipsum dolore\n"+
"sit amet, lorem ipsum\n"+
"dolore sit amet."

# Escape Characters:
"You can add\tTabs, \" Quote, \\ Backslash…"

# Hex Characters:
"It was character A : \x41"

Not Supported Operators in Edify

There is a lot of operator features in common programming languages that not supported by edify, like assignment operator for inserting something into variable, bitwise operator for manipulating bits within integer, and arithmetic operators for doing simple math calculations.

All this limited has been added via functions (except bitwise),

but only available for aroma-config script

, and

only simple operations supported

.
​

What UI's AROMA Installer Supported

AROMA Installer had 4 main type of Customizable User Interfaces, the Wizard UI, Dialog UI, Splash UI and Installer UI. And un-customizable Menu UI for selecting About, Help, Tools and Quit Installer.​

Wizard UI

The Wizard UI was the main User Interface in AROMA Installer, it's contain Back and Next button in navigation bar just like Computer common Installer programs (Windows Installer, NSIS Install System, InstallShield). Users can navigate trough the screens, or back to previous screens if something not right in configurations. Users can select Typical or Customize installations, and Users can customize what packages to install.

AROMA Installer support many Wizard UI, and here the completed list of it's UI:

checkbox – UI to show checkboxes in groupable list, the selected items will be saved in prop format, and can be accessed with file_getprop.

selectbox – It's like checkbox, but it's only able to check 1 items per group.

textbox – It will show the textbox, you can read text file to show it into the textbox

viewbox – It's like Textbox, but not scrollable, and only supported limited text length

agreebox – It's like Textbox, but with agree checkbox, user can't step to next page if the checkbox not already checked. Useful to show License or Terms of Use Interface.

menubox – This UI will show list of menu to select, there is no Next button, because when User select the item, it will automatically step into next page. And The selected menu will be saved in temporary prop file.

Dialog UI

While Wizard UI will shown it's interface in Fullscreen, the Dialog UI will shown it's interface in Popup Window, It was useful for some needs, like show confirmation for "Are You Sure want to format the partitions?", or show Alert Dialog for "Thanks for using my ROM". Here the complete list of Dialog UI in AROMA Installer:

alert – Show popup dialog, with limited text length and Only the OK button.

confirm – Show popup dialog, with limited text length and contains 2 customizable Button "Yes" and "No", with return value true for "Yes" and false for "No".

textdialog – Show scrollable text popup dialog, with long text length support and Only OK Button.

Splash UI

This UI Simply show the Splash Screen from png files with custom delay before it show next page. The image will automatically position in center of screen depended from it's image size. The background will be blended in blur and darkest color.​

Installer UI

When configuration invoke the install UI, it will start an installation, and show the installer UI with description text on top window, textbox for installer information in middle, and progress text and bar in bottom of screen. The installation will not cancelable, and there is no buttons or menu to select before installation finished, The Next and Save Logs button will be shown after installation finished. And next Wizard UI can't do Back command beyond this installer UI, so the Installer UI will only shown once time only in flash process.​

What Functions AROMA Installer Supported

There is so many functions that you can used for your needs, The available functions was the common functions that may be usable for installations, but not supported very complex things. AROMA Installer support simple comparison, math, system partition information, and simple set and get variables.

Here the list of functions that you can used:

setcolor – Set UI Color Scheme

ini_set – Set Aroma Configuration settings

calibrate – Calibrating Touch Screen

getvar – Get Variable

setvar – Set Variable

appendvar – Append string into variable

prependvar – Prepend string into variable

file_getprop – Get prop value of some key from prop file.

readfile – Read text file from zip content

readfile_aroma – Read text file from zip content relatively from aroma META-INF folder.

getdisksize – Get partition total size

getdiskfree – Get partition free size

getdiskusedpercent – Get partition used size in percentage

cmp – Simple integer comparison ( >, <, ==, >=, <=, != )

cal – Simple math calculator ( +, -, /, * )

iif – Inline if

if else – If and Else Statement

pleasewait – Show please wait/loading progress when calculating/doing hard process that took a lot of time.

writetmpfile – Write/create temporary file with text contents

exit – terminate installation.

Custom Fonts

You can customize your AROMA Installer Fonts. The AROMA Installer use 2 type of fonts "Big" and "Small", the Big font used in Title and the Small Font used in almost any controls. To use the custom fonts, copy the big.png or small.png into META-INF/com/google/android/aroma/fonts.

List of Custom Fonts Currently Available to Download - by amarullz

​

Download Custom Fonts ( 5 Fonts ) [+]​

Create Your Own Font

You can also create your own fonts, it was plain png (32 bit color depth). All letter was arranged in ASCII order Start from ASCII 32 (space) to ASCII 95 ( ~ char) then ( © - Copyright ) character.

Here the letter list:

!”#$%&’()*+,-./0123456789:;<=>?@ABCDEFGHI JKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~©

In the first row picture, there is pixel to seperate one letter to next letter, because AROMA Installer didn't use fixed size fonts ( console fonts like courier ). The fonts will rendering from 2nd row into end of rows. Here the example:

​

NOTE: AROMA Installer only need alpha channel for this, the color of fonts will using the AROMA color scheme defined in aroma-config. The width separator (in first row pixel) should be full opaque (alpha=100% or 255).

If you make your own fonts, please fell free to post here...
​

Other Custom Fonts

You can also use third party custom fonts created by other xda-developers users. Here some custom font list:

Monospace Font - by mickey-r