Developer ToolChain Introduction
From berofix - professional SIP gateway
First steps in the bero*fix User-AppFS Development Environment
A note
This Toolchain will be deprecated. When the berofix UserApp Framework is released, it will replace the old toolchain.
An introduction to baf can be found under BAF - berofix UserApp Framework [1].
Prerequisites
* PC running VirtualBox 4.x or higher * bero*fix-card with AppFS v2.x or higher
Installation of the virtual machine
Download the file UserAppFSDevEnv.ova from your beroCloud account and import it to your VirtualBox as described on this page:
http://www.virtualbox.org/manual/ch01.html#ovf
Introduction to the Development Environment
After the virtual machine has booted up, a default Ubuntu Desktop is shown and you are logged in as user 'berofix' with the same password. On the desktop you'll find three shortcuts, one opens a terminal in the UserAppFS-Repository, the other opens the filebrowser and the last one opens this introduction.
Since the Linux Distribution used is Ubuntu, the root-account is disabled, but you can still use 'sudo' to do administrative task, such as installing your favorite development environment tools.
The desktop shown after boot-up contains three icons:
1) this documentation 2) the folder where the repository lies 3) a terminal that opens in the repository
The shell used on this system is a preconfigured zsh which displays software- repositories after the following scheme:
repository[branch]:/.$
Depending of the status of the repository it also shows up to two symbols:
⚡ -- for unstaged changes ⚠ -- for staged changes
Hierarchy of the Repository
* build: Contains the Makefiles used to control the build-process. * conf: Contains configuration files. * deps: Contains the compiler-suite and libraries used on the rootfs and appfs of bero*fix. * pkg: After successfull build this folder contains installable tar-archives of the UserAppFS. * pkg-info: Contains files with information about the package, currently only one file is mandatory: VERSION * skel: Contains a basic skeleton of the filesystem-hierarchy of the UserAppFS. * src: Contains the sources of the applications to be installed on the UserAppFS. * tools: Contains scripts needed to support the build-process or its preparation.
Building and installing your first UserAppFS
Open a terminal by clicking on the 'Open Terminal in UserAppFS Repository' shortcut and type:
make
After the build-process is done you can find the resulted UserAppFS-package in the pkg/ directory and install it like you'd install a regular AppFS on your bero*fix-card using the Firmware-Update page.
Depending on whether the you've enabled the UserAppFS on your bero*fix, you will be greeted by a placeholder next time you open the the web-frontend of your bero*fix.
How an app is build for the UserAppFS
The build-process of an app consists of three steps:
1) copy or extract source from 'src/' to 'build/work/' 2) run configure-script and/or make 3) install resulting app to 'work/target/home/admin/apps/<appname>/'
For this, the Makefile in the root-directory of the repository calls the Makefile in the 'build/' directory and this Makefile calls every other Makefile in this directory (sorted after priority).
The other Makefiles in the 'build/' directory are named after the scheme 'Makefile-<priority>-<appname>'.
Each application needs its own Makefile in this directory and these Makefiles control how an app is configured, built and installed. To prevent an app from being built and included in the UserAppFS, just append '_disabled' to the filename of it's Makefile in this directory.
There are several settings that can be adjusted:
APP_NAME: defines the name of an application. APP_VERS: defines the version of an application.
Those two variables are used to build the name of the source-folder or archive and the target-folder.
CONF_OPTS: set options to be passed to the configure-script of an app.
It is not evaluated, if your application does not use configure.
SUB_DIRS: directory-names given here are created in the UserAppFS
under '/home/admin/apps/<appname>/'. This is only useful if the install-rule of the apps Makefile does not create those folders.
The other variables usually do not need to be changed.
Porting an app to bero*fix
To port an app to bero*fix, you need to store the source-package of that specific app in the 'src/files/' folder inside the repository. You will also have to create an Makefile inside the 'build/' directory. Best thing is to start with the example given with 'build/Makefile-03-nano', as it cross-compiles the editor nano for bero*fix. There are a few things to be considered when porting an app to bero*fix:
Size: An UserApp for a bero*fix-card can only consume up to 8 slots (~ 8MB),
so try to keep the ported app smaller and remove or disable all features not necessary.
Access: Even though an userappfs-application can read the contents of
folders like '/home/admin/' or '/usr/local/', it cannot write to them.
All temporary-files should be saved in '/tmp/', all configuration
files that are to survive a power-loss in '/usr/conf/'. The installation-process of an UserApp creates symlinks that point to these directories: '/home/admin/apps/<appname>/etc' -> '/usr/conf/userapp' '/home/admin/apps/<appname>/var' -> '/tmp/userapp'
Network: UserAppFS-applications that run as daemon are started with
the privileges of the user 'admin'.
That means, that they can not open TCP or UDP ports below 1024,
mount or unmount filesystems or restart the system.
If your app has configuration files, it's the safest to store them in '/home/admin/apps/<appname>/etc'. Temporary files are to be stored in '/tmp/' or '/home/admin/apps/<appname>/var/log' (if those files are logfiles) or '/home/admin/apps/<appname>/var/run' (if they contain runtime information, such as PID).
Some apps require preparation-tasks, that need to be done after the installation of your UserAppFS and / or removal tasks, that have to be done before the UserAppFS is removed or replaced by another version or kind of UserAppFS. The scripts which execute those task can be found in 'skel/setup' and are named 'post_install.sh' for tasks that are to be done after the installation and 'pre_remove.sh' for tasks that are to be done before removing an UserAppFS.
Creating a HTML- / PHP-Frontend for the UserAppFS
To make several settings of apps installed on the UserAppFS (e.g. options for services) configurable for the user, bero*fix allows the implementation of an UserAppFS-Webfrontend. If an UserAppFS is installed, enabled and the folder '/home/admin/apps/<appname>/www/' contains a file named 'index.php', a link to that page will be listed in the the bero*fix-GUI under the menu 'APPS'. It is also accessible through 'http://<BEROFIXIP>/userapp/<appname>'
If you are creating a 'master' UserApp, the page will be displayed instead of the original bero*fix-GUI, if the UserAppFS has been enabled.
One last note to the UserAppFS-webfrontend if you are developing a 'master'-UserApp: It is advisable to include an easy accessible link to '/app/berogui' so that the users of your UserAppFS are able to switch to the bero*fix-GUI.
Setting Name, Version and Description of your UserAppFS
To make it easy for users of bero*fix to distinguish between several UserAppFS-packages and versions, the repository contains a VERSION-file that contains information about the current UserAppFS. It is located in the directory pkg_info and should be edited before shipping any version of your UserAppFS. The first field 'TYPE' is constant and needs to be set to 'userappfs', the second field 'VERSION' should contain the version of your UserAppFS, the fields 'NAME' and 'DESCRIPTION' are self-explanatory and not discussed here. There are two types of UserAppFS-packages that can be created: slaves and master. A slave package adds simple functionality to a bero*fix like additional software, while a master package is used to replace or complement the bero*fix-GUI. The type of a package is specified in the field 'CLASS'. The capacity of the UserAppFS is divided in slots. One slot stands for 1 MB of used storage. The maximum slots that can be used in total is 8, so you can have one UserApp that is 8 slots big or 4 UserApps that take 2 slots each. Please define the correct size of your UserApp in the field 'SLOTS'.
Howto keep it small
As mentioned before, the UserAppFS has only 8 slots (~ 8 MB) of space available, so it's important to keep the applications slim.
One space-eater are man- and info-pages, which are typically not important on a device like bero*fix. So if one or more of your apps installs manpages, check if you can disable that in their configure-script or if not, delete them after the build- and install-process is complete. The build/Makefile contains a section 'strip', just add a 'rm -rfv $(TARGET)/home/admin/apps/<appname>/path/to/manpages' there and the manpages will be deleted before the package is created.
Another way to reduce the size of your apps is to strip them. While this is usually unhandy if you're debugging, it can safely be done on release. For this, build/Makefile, section 'strip' is of importance also. There are already a few examples for locations of binaries that are stripped before they are packed.
The resulting file-structure of an UserApp
A typical UserApp-package will result in the following file-/directory-structure:
/home/admin/
apps/
app1/
bin/
*bin1
*bin2
*bin3
init/
*S01startscript
*S02startscript
www/
index.php
init/
*rcK
*rcS
setup/
*get_slots_used.sh
*post_install.sh
*pre_remove.sh
www/
index.php
VERSION
content.txt
After installation the script 'post_install.sh' adds a few useful symlinks:
/home/admin/
apps/
app1/
etc -> /home/admin/etc
var -> /home/admin/var
etc -> /usr/conf/userapp
var -> /tmp/userapp
and the files 'VERSION' and 'context.txt' are copied to '/home/admin/apps/app1/'.
That's all folks
Well, not at all. If you have questions, want to report problems or have suggestions, mail them to us:
support@beronet.com
