README.md

   1 # AGL Framework Binder
   2
   3 This project provides the binder component of the the microservice architecture
   4 of Automotive Grade Linux (AGL).
   5
   6 This project is available there https://git.automotivelinux.org/src/app-framework-binder/
   7
   8 It can be cloned with **git clone https://git.automotivelinux.org/src/app-framework-binder**.
   9
  10
  11 ## License and copying
  12
  13 This software is an open source software funded by LinuxFoundation and Renesas.
  14
  15 This software is delivered under the terms of the open source license Apache 2.
  16
  17 This license is available in the file LICENSE-2.0.txt or on the worl wide web at the
  18 location https://opensource.org/licenses/Apache-2.0
  19
  20
  21 ## Building
  22
  23 ### Requirements
  24
  25 Building the AGL framework binder has been tested under
  26   **Ubuntu**, **Debian** and **Fedora 26** with gcc 6 and 7.
  27
  28 It requires the following libraries:
  29
  30  * libmagic ("libmagic-dev" under Ubuntu, "file-devel" under Fedora);
  31  * libmicrohttpd >= 0.9.60  (fetch and build from "http://ftp.gnu.org/gnu/libmicrohttpd");
  32  * json-c ("libjson-c-dev/devel");
  33  * uuid ("uuid-dev/libuuid-devel");
  34  * openssl ("libssl-dev/openssl-devel");
  35  * systemd >= 222 ("libsystemd-dev/systemd-devel");
  36
  37 The following library can be used for checking permissions:
  38
  39  * cynara (https://github.com/Samsung/cynara)
  40
  41 and the following tools:
  42
  43  * gcc;
  44  * pkg-config;
  45  * cmake >= 3.0
  46
  47 To install all dependencies under Ubuntu (excepting libmicrohttpd), please type:
  48
  49         $ apt-get install libmagic-dev libjson-c-dev uuid-dev libsystemd-dev libssl-dev gcc make pkg-config cmake
  50
  51 or under Fedora (excepting libmicrohttpd and rtl-sdr):
  52
  53         $ dnf install git passwd iproute openssh-server openssh-client
  54         $ dnf install file-devel gcc gdb make pkgconfig cmake
  55         $ dnf install json-c-devel libuuid-devel systemd-devel openssl-devel
  56
  57 ### Simple compilation
  58
  59 The following commands will install the binder in your subdirectory
  60 **$HOME/local** (instead of **/usr/local** the default when
  61 *CMAKE_INSTALL_PREFIX* isn't set).
  62
  63         $ git clone https://git.automotivelinux.org/src/app-framework-binder
  64         $ cd app-framework-binder
  65         $ mkdir build
  66         $ cd build
  67         $ cmake -DCMAKE_INSTALL_PREFIX=$HOME/local ..
  68         $ make install
  69
  70 ### Advanced compilation
  71
  72 You can tune options when calling cmake. Here are the known options with
  73 their default values.
  74
  75         $ git clone https://git.automotivelinux.org/src/app-framework-binder
  76         $ cd app-framework-binder
  77         $ mkdir build
  78         $ cd build
  79         $ cmake \
  80               -DCMAKE_INSTALL_PREFIX=/usr/local  \
  81               -DAGL_DEVEL=OFF                    \
  82               -DINCLUDE_MONITORING=OFF           \
  83               -DINCLUDE_SUPERVISOR=OFF           \
  84               -DINCLUDE_DBUS_TRANSPARENCY=OFF    \
  85               -DINCLUDE_LEGACY_BINDING_V1=OFF    \
  86               -DINCLUDE_LEGACY_BINDING_VDYN=OFF  \
  87               -DAFS_SUPERVISOR_PORT=1619         \
  88               -DAFS_SUPERVISOR_TOKEN="HELLO"     \
  89               -DAFS_SUPERVISION_SOCKET="@urn:AGL:afs:supervision:socket" \
  90               -DUNITDIR_SYSTEM=${CMAKE_INSTALL_LIBDIR}/systemd/system    \
  91             ..
  92         $ make install
  93
  94 The configuration options are:
  95
  96 | Variable                    | Type    | Feature
  97 |:----------------------------|:-------:|:------------------------------
  98 | AGL_DEVEL                   | BOOLEAN | Activates development features
  99 | INCLUDE_MONITORING          | BOOLEAN | Activates installation of monitoring
 100 | INCLUDE_SUPERVISOR          | BOOLEAN | Activates installation of supervisor
 101 | INCLUDE_DBUS_TRANSPARENCY   | BOOLEAN | Allows API transparency over DBUS
 102 | INCLUDE_LEGACY_BINDING_V1   | BOOLEAN | Includes the legacy Binding API version 1
 103 | INCLUDE_LEGACY_BINDING_VDYN | BOOLEAN | Includes the legacy Binding API version dynamic
 104 | AFS_SUPERVISOR_PORT         | INTEGER | Port of service for the supervisor
 105 | AFS_SUPERVISOR_TOKEN        | STRING  | Secret token for the supervisor
 106 | AFS_SUPERVISION_SOCKET      | STRING  | Internal socket path for supervision (internal if starts with @)
 107 | UNITDIR_SYSTEM              | STRING  | Path to systemd system unit files for installing supervisor
 108
 109
 110
 111
 112 ***** TO BE COMPLETED *****
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125 ## Simple demo
 126
 127
 128
 129
 130 ### Testing/Debug
 131
 132 ```
 133 $ ${AFB_DAEMON_DIR}/build/src/afb-daemon --help
 134 $ ${AFB_DAEMON_DIR}/build/src/afb-daemon --port=1234 --token='' --ldpaths=${AFB_DAEMON_DIR}/build --workdir=/tmp --rootdir=${AFB_DAEMON_DIR}/test
 135 ```
 136
 137 ### Starting
 138
 139 ```
 140 $ afb-daemon --help
 141 $ afb-daemon --verbose --port=<port> --token='' --workdir=<working directory> --rootdir=<web directory (index.html)>
 142 ```
 143
 144 ### Example
 145
 146 ```
 147 $ afb-daemon --verbose --port=1234 --token='' --workdir=/tmp --rootdir=/srv/www/htdocs --alias=icons:/usr/share/icons
 148 ```
 149
 150 ### Directories & Paths
 151
 152 Default behaviour is to locate ROOTDIR in $HOME/.AFB
 153
 154 ### REST API
 155
 156 Developers are intended to provide a structure containing : API name, corresponding methods/callbacks, and optionally a context and a handle.
 157 A handle is a void* structure automatically passed to API callbacks.
 158 Callbacks also receive HTTP GET data as well as HTTP POST data, in case a POST method was used.
 159 Every method should return a JSON object or NULL in case of error.
 160
 161 API plugins can be protected from timeout and other errors. By default this behaviour is deactivated, use --apitimeout to activate it.
 162
 163         STATIC AFB_restapi myApis[]= {
 164           {"ping"    , AFB_SESSION_NONE,  (AFB_apiCB)ping,     "Ping Function"},
 165           {"action1" , AFB_SESSION_CHECK, (AFB_apiCB)action1 , "Action-1"},
 166           {"action2" , AFB_SESSION_CHECK, (AFB_apiCB)action2 , "Action-2"},
 167           {NULL}
 168         };
 169
 170         PUBLIC AFB_plugin *pluginRegister () {
 171             AFB_plugin *plugin = malloc (sizeof (AFB_plugin));
 172             plugin->type  = AFB_PLUGIN_JSON;
 173             plugin->info  = "Plugin Sample";
 174             plugin->prefix= "myPlugin";
 175             plugin->apis  = myApis;
 176             return (plugin);
 177         }
 178
 179 ### HTML5 and AngularJS Redirects
 180
 181 Binder supports HTML5 redirect mode even with an application baseurl.
 182 Default value for application base URL is /opa.
 183 See Application Framework HTML5 Client template at https://github.com/iotbzh/afb-client-sample
 184
 185 If the Binder receives something like _http://myopa/sample_ when sample is not the homepage of the AngularJS OPA,
 186 it will redirect to _http://myopa/#!sample_.
 187 This redirect will return the _index.html_ OPA file and will notify AngularJS not to display the homepage, but the sample page.
 188
 189 Warning: in order for AngularJS applications to be able to work with both BASEURL="/" and BASEURL="/MyApp/", all page references have to be relative.
 190
 191 Recommended model is to develop with a BASEURL="/opa" as any application working with a BASEURL will work without, while the opposite is not true.
 192
 193 Note: If a resource is not accessible from ROOTDIR then the "--alias" switch should be used, as in: --alias=/icons:/usr/share/icons.
 194 Only use alias for external support static files. This should not be used for API and OPA.
 195
 196
 197 ### Ongoing work
 198
 199 Javascript plugins. As of today, only C plugins are supported, but JS plugins are on the TODO list.