diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | README.md | 83 | ||||
| -rw-r--r-- | cmake/common.cmake | 1 | ||||
| -rw-r--r-- | cmake/config.cmake.sample | 33 | ||||
| -rw-r--r-- | rpm/rpm-config.spec.in | 2 | ||||
| -rw-r--r-- | wgt/config.xml.in | 4 | ||||
| -rw-r--r-- | wgt/config.xml.in.sample | 142 |
7 files changed, 217 insertions, 49 deletions
@@ -8,3 +8,4 @@ Makefile nbproject .vscode *.tar.gz +.*.sw* @@ -12,11 +12,11 @@ isn't recommended now to handle project build especially in a multiuser project because CMake will not be aware of new or removed source files. You'll find simple usage example for different kind of target under the `examples` folder. -More advanced usage can be saw with the [CAN_signaling binding](https://github.com/iotbzh/CAN_signaling) -which mix external libraries, binding, and html5 hybrid demo application. +More advanced usage can be saw with the [low-level-can-service](https://gerrit.automotivelinux.org/gerrit/apps/low-level-can-service) +which mix external libraries, binding. Typical project architecture ------------------------------ +--------------------------------- A typical project architecture would be : @@ -35,11 +35,15 @@ A typical project architecture would be : │ │ │ └── config.spec.in │ │ └── wgt/ │ │ ├── config.xml.in -│ │ └── icon.png +│ │ ├── config.xml.in.sample +│ │ ├── icon-default.png +│ │ ├── icon-html5.png +│ │ ├── icon-native.png +│ │ ├── icon-qml.png +│ │ └── icon-service.png │ ├── packaging/ │ │ ├── config.xml │ │ ├── config.spec -│ │ ├── icon.png │ │ └── config.deb │ ├── autobuild/ │ │ ├── agl @@ -69,32 +73,25 @@ A typical project architecture would be : Usage ------ -Install the reference files to the root path of your project, then once -installed, customize your project with file `\<root-path\>/etc/config.cmake`. - -Typically, to copy files use a command like: +To use these templates files on your project just install the reference files using **git submodule** then use `config.cmake` file to configure your project specificities : ```bash -cp -r reference/etc reference/packaging <root-path-to-your-project> -cp reference/AGLbuild <root-path-to-your-project> +git submodule add https://gerrit.automotivelinux.org/gerrit/apps/app-templates conf.d/default ``` Specify manually your targets, you should look at samples provided in this -repository to make yours. Then when you are ready to build, using `AGLbuild` +repository to make yours. Then when you are ready to build, using `autobuild` that will wrap CMake build command: ```bash -./build.sh package +./conf.d/default/autobuild/agl/autobuild.mk package ``` -AGLbuild is not mandatory to build your project by will be used by `bitbake` -tool when building application from a Yocto workflow that use this entry point -to get its widget file. - Or with the classic way : ```bash -mkdir -p build && cd build +mkdir -p build +cd build cmake .. && make ``` @@ -121,13 +118,30 @@ INSTALL(TARGETS ${TARGET_NAME}.... populate_widget() --> add target to widget tree depending upon target properties ``` -### Build a widget using provided macros +### Build a widget + +#### config.xml.in file + +To build a widget you need to configure file _config.xml_. This repo +provide a simple default file _config.xml.in_ that will be configured using the +variable set in _config.cmake_ file. + +> ***CAUTION*** : The default file is only meant to be use for a +> simple widget app, more complicated ones which needed to export +> their api, or ship several app in one widget need to use the provided +> _config.xml.in.sample_ which had all new Application Framework +> features explained and examples. + +#### Using cmake template macros To leverage all macros features, you have to specify ***properties*** on your targets. Some macros will not works without specifying which is the target type. -As the type is not always specified for some custom target, like an ***HTML5*** + +As the type is not always specified for some custom targets, like an ***HTML5*** application, macros make the difference using ***LABELS*** property. +Example: + ```cmake SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES LABELS "HTDOCS" @@ -144,19 +158,22 @@ definition. Then at the end of your project definition you should use the macro `wgtpkg-pack` Application Framework tools. Macro reference ----------------- +-------------------- ### PROJECT_TARGET_ADD Typical usage would be to add the target to your project using macro -`PROJECT_TARGET_ADD` with the name of your target as parameter. Example: +`PROJECT_TARGET_ADD` with the name of your target as parameter. + +Example: ```cmake PROJECT_TARGET_ADD(low-can-demo) ``` -This will make available the variable `${TARGET_NAME}` set with the specificied -name. +> ***NOTE***: This will make available the variable `${TARGET_NAME}` +> set with the specificied name. This variable will change at the next call +> to this macros. ### project_subdirs_add @@ -170,13 +187,21 @@ Usage : project_subdirs_add() ``` +You also can specify a globbing pattern as argument to filter which folders will be looked for. + +To filter all directories that begin with a number followed by a dash the anything: + +```cmake +project_subdirs_add("[0-9]-*") +``` + ### project_targets_populate Macro use to populate widget tree. To make this works you have to specify some properties to your target : -- LABELS : specify *BINDING*, *HTDOCS*, *EXECUTABLE*, *DATA* -- PREFIX : must be empty **""** when target is a *BINDING* else default prefix *lib* will be applied -- OUTPUT_NAME : Name of the output file generated, useful when generated file name is different from `${TARGET_NAME}` +* LABELS : specify *BINDING*, *HTDOCS*, *EXECUTABLE*, *DATA* +* PREFIX : must be empty **""** when target is a *BINDING* else default prefix *lib* will be applied +* OUTPUT_NAME : Name of the output file generated, useful when generated file name is different from `${TARGET_NAME}` Always specify `populate_widget()` macro as the last statement, especially if you use ${TARGET_NAME} variable. Else variable will be set at wrong value with @@ -185,7 +210,7 @@ the **populate_** target name. Usage : ```cmake -populate_widget() +project_targets_populate() ``` ### project_package_build @@ -197,7 +222,7 @@ directory : Usage : ```cmake -build_widget() +project_package_build() ``` ### project_closing_message diff --git a/cmake/common.cmake b/cmake/common.cmake index 18dfeae..d88f89c 100644 --- a/cmake/common.cmake +++ b/cmake/common.cmake @@ -194,7 +194,6 @@ macro(wgt_package_build) set(WIDGET_ENTRY_POINT lib CACHE STRING "the widget entry point file") configure_file(${WIDGET_CONFIG_TEMPLATE} ${PROJECT_PKG_BUILD_DIR}/config.xml) - configure_file(${WIDGET_CONFIG_TEMPLATE} ${PROJECT_PKG_ENTRY_POINT}/config.xml) file(COPY ${WGT_TEMPLATE_DIR}/icon-default.png DESTINATION ${PROJECT_PKG_BUILD_DIR}) file(RENAME ${PROJECT_PKG_BUILD_DIR}/icon-default.png ${PROJECT_PKG_BUILD_DIR}/${PROJECT_ICON}) diff --git a/cmake/config.cmake.sample b/cmake/config.cmake.sample index 514a80f..793c2a0 100644 --- a/cmake/config.cmake.sample +++ b/cmake/config.cmake.sample @@ -26,7 +26,7 @@ set(PROJECT_URL "https://gerrit.automotivelinux.org/gerrit/apps/app-templates") set(PROJECT_ICON "icon.png") set(PROJECT_AUTHOR "Last Name, First Name") set(PROJECT_AUTHOR_MAIL "example.man@bigouden.bzh") -set(PROJECT_LICENCE "APL2.0") +set(PROJECT_LICENSE "APL2.0") set(PROJECT_LANGUAGES,"C") # Where are stored default templates files from submodule or subtree app-templates in your project tree @@ -84,24 +84,27 @@ set(LD_LIBRARY_PATH ${CMAKE_INSTALL_PREFIX}/lib64 ${CMAKE_INSTALL_PREFIX}/lib) # ----------------------------------- #set(WIDGET_CONFIG_TEMPLATE ${CMAKE_CURRENT_SOURCE_DIR}/conf.d/config.xml.in) -# Mandatory widget Mimetype specification -# -------------------------------------------------- +# Mandatory widget Mimetype specification of the main unit +# -------------------------------------------------------------------------- # Choose between : -# - application/vnd.agl.service -# - application/vnd.agl.native -# - application/x-executable -# - text/html +#- text/html : HTML application, +# content.src designates the home page of the application +# +#- application/vnd.agl.native : AGL compatible native, +# content.src designates the relative path of the binary. +# +# - application/vnd.agl.service: AGL service, content.src is not used. +# +#- ***application/x-executable***: Native application, +# content.src designates the relative path of the binary. +# For such application, only security setup is made. # set(WIDGET_TYPE MimeType_Not_Set) -# Mandatory Widget entry point file. -# ---------------------------------------------------- -# This is the file that will be executed, loaded,... -# at launch time by the application framework -# -# !IMPORTANT! : Service Widget Mimetype has to specified -# the WIDGET_ENTRY_POINT "lib" which is the default directory -# that holds the bindings. +# Mandatory Widget entry point file of the main unit +# -------------------------------------------------------------- +# This is the file that will be executed, loaded, +# at launch time by the application framework. # set(WIDGET_ENTRY_POINT EntryPoint_Path_Not_Set) diff --git a/rpm/rpm-config.spec.in b/rpm/rpm-config.spec.in index 31a2a0a..0383102 100644 --- a/rpm/rpm-config.spec.in +++ b/rpm/rpm-config.spec.in @@ -20,7 +20,7 @@ Name: @PROJECT_NAME@ Version: @PROJECT_VERSION@ Release: 1 -License: @PROJECT_LICENCE@ +License: @PROJECT_LICENSE@ Summary: @PROJECT_DESCRIPTION@ Url: @PROJECT_URL@ Source0: %{name}_%{version}.orig.tar.gz diff --git a/wgt/config.xml.in b/wgt/config.xml.in index 250878a..35d20b8 100644 --- a/wgt/config.xml.in +++ b/wgt/config.xml.in @@ -5,7 +5,5 @@ <content src="@WIDGET_ENTRY_POINT@" type="@WIDGET_TYPE@"/> <description>@PROJECT_DESCRIPTION@</description> <author>@PROJECT_AUTHOR@ <@PROJECT_AUTHOR_MAIL@></author> - <license>@PROJECT_LICENCE@</license> + <license>@PROJECT_LICENSE@</license> </widget> - - diff --git a/wgt/config.xml.in.sample b/wgt/config.xml.in.sample new file mode 100644 index 0000000..b93f3d9 --- /dev/null +++ b/wgt/config.xml.in.sample @@ -0,0 +1,142 @@ +<?xml version="1.0" encoding="UTF-8"?> +<widget xmlns="http://www.w3.org/ns/widgets" id="@PROJECT_NAME@" version="@PROJECT_VERSION@"> + <name>@PROJECT_NAME@</name> + <icon src="@PROJECT_ICON@"/> + <content src="@WIDGET_ENTRY_POINT@" type="@WIDGET_TYPE@"/> + <description>@PROJECT_DESCRIPTION@</description> + <author>@PROJECT_AUTHOR@ <@PROJECT_AUTHOR_MAIL@></author> + <license>@PROJECT_LICENSE@</license> + +<!-- Feature : required-api ------------------------------------------------------ +#### param name="#target" OPTIONAL + +Declares the name of the unit requiring the listed apis. +Only one instance of the param "#target" is allowed. +When there is not instance of this param, it behave as if +the target main was specified. + +#### param name=[required api name] + +The name is the name of the required API. +The value describes how to connect to the required api. +It is either: + + - local: The binding is a local shared object. + In that case, the name is the relative path of the + shared object to be loaded. + - auto: The framework set automatically the kind of + the connection to the API + - ws: The framework connect using internal websockets + - dbus: The framework connect using internal dbus + - link: The framework connect in memory by dinamically linking + +Example: + <feature name="urn:AGL:widget:required-api"> + <param name="#target" value="low-can" /> + <param name="<a-required-api>" value="auto" /> + <param name="<another-required-api>" value="auto" /> + </feature> +---------------------------------------------------------------------------------> + +<!-- Feature : required-permission ------------------------------------------ + +List of the permissions required by the unit. +Each required permission must be explicited using a <param> entry. + +#### param name="#target" OPTIONAL + +Declares the name of the unit requiring the listed permissions. +Only one instance of the param "#target" is allowed. +When there is not instance of this param, it behave as if +the target main was specified. + +#### param name=[required permission name] + +The value is either: +- required: the permission is mandatorily needed except if the feature +isn't required (required="false") and in that case it is optional. +- optional: the permission is optional + +Example: +<feature name="urn:AGL:widget:required-permission"> + <param name="#target" value="geoloc" /> + <param name="urn:AGL:permission:real-time" value="required" /> + <param name="urn:AGL:permission:syscall:*" value="required" /> +</feature> +---------------------------------------------------------------------------------> + +<!-- Feature : provided-unit ------------------------------------------------- +This feature is made for declaring new units +for the widget. Using this feature, a software publisher +can provide more than one application in the same widget. + +#### param name="#target" REQUIRED + +Declares the name of the unit. The default unit, the unit +of the main of the widget, has the name "main". The value +given here must be unique within the widget file. It will +be used in other places of the widget config.xml file to +designate the unit. + +Only one instance of the param "#target" is allowed. +The value can't be "main". + +#### param name="content.type" REQUIRED + +The mimetype of the provided unit. + +#### param name="content.src" + +A path to the file (subject to localisation), this is the entry point +to that unit. + +#### other parameters + +The items that can be set for the main unit +can also be set using the params if needed. + + - description + - name.content + - name.short + - ... + +Example: +<feature name="urn:AGL:widget:provided-unit"> + <param name="#target" value="geoloc" /> + <param name="description" value="binding of name geoloc" /> + <param name="content.src" value="index.html" /> + <param name="content.type" value="application/vnd.agl.service" /> +</feature> +---------------------------------------------------------------------------------> + +<!-- Feature: provided-api --------------------------------------------------- +Use this feature for exporting one or more API of a unit +to other widgets of the platform. + +This feature is an important feature of the framework. + +#### param name="#target" OPTIONAL + +Declares the name of the unit exporting the listed apis. +Only one instance of the param "#target" is allowed. +When there is not instance of this param, it behave as if +the target main was specified. + +#### param name=[name of exported api] + +The name give the name of the api that is exported. + +The value is one of the following values: + +- ws: export the api using UNIX websocket +- dbus: export the API using dbus +- auto: export the api using the default method(s). + +Example: +<feature name="urn:AGL:widget:provided-api"> + <param name="#target" value="geoloc" /> + <param name="geoloc" value="auto" /> + <param name="moonloc" value="auto" /> +</feature> +---------------------------------------------------------------------------------> +</widget> |