nbproject
.vscode
*.tar.gz
+.*.sw*
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 :
│ │ │ └── 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
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
```
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"
`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
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
Usage :
```cmake
-populate_widget()
+project_targets_populate()
```
### project_package_build
Usage :
```cmake
-build_widget()
+project_package_build()
```
### project_closing_message
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})
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
# -----------------------------------
#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)
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
<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>
-
-
--- /dev/null
+<?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>
Code Review / staging / xdg-launcher.git / commitdiff