From: Romain Forlot Date: Tue, 4 Jul 2017 17:00:40 +0000 (+0200) Subject: Update doc & use gitbook to enhance doc generation X-Git-Tag: dab_3.99.3~28 X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=commitdiff_plain;h=b1bb356be470cfc10a0d9457166ad21af0bd3f19;p=staging%2Fxdg-launcher.git Update doc & use gitbook to enhance doc generation Change-Id: If42c916f7664ea67b818a21b8f50c66c41e11f89 Signed-off-by: Romain Forlot --- diff --git a/.gitignore b/.gitignore index 8164213..507c195 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,4 @@ nbproject .vscode *.tar.gz .*.sw* +_book diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..93b07d3 --- /dev/null +++ b/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "{}" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2017 claneys + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/README.md b/README.md index 6dce651..94aa6be 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,78 @@ You'll find usage samples here: - [audio-binding](https://github.com/iotbzh/audio-binding) - [unicens2-binding](https://github.com/iotbzh/unicens2-binding) -## Typical project architecture +## Quickstart + +### Initialization + +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 +git submodule add https://gerrit.automotivelinux.org/gerrit/apps/app-templatesconf.d/app-templates conf.d/app-templates +mkdir conf.d/cmake +cp conf.d/app-templates/cmake/config.cmake.sample conf.d/cmake/config.cmake +``` + +Edit the copied config.cmake file to fit your needs. + +Now, create your top CMakeLists.txt file which include `config.cmake` file. + +An example is available in **app-templates** submodule that you can copy and +use: + +```bash +cp conf.d/app-templates/cmake/CMakeLists.txt CMakeLists.txt +``` + +### Create your CMake targets + +For each target part of your project, you need to use ***PROJECT_TARGET_ADD*** +to include this target to your project. + +Using it, make available the cmake variable ***TARGET_NAME*** until the next +***PROJECT_TARGET_ADD*** is invoked with a new target name. + +So, typical usage defining a target is: + +```cmake +PROJECT_TARGET_ADD(SuperExampleName) --> Adding target to your project + +add_executable/add_library(${TARGET_NAME}.... --> defining your target sources + +SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES.... --> fit target properties +for macros usage + +INSTALL(TARGETS ${TARGET_NAME}.... +``` + +### Targets PROPERTIES + +You should set properties on your targets that will be used to package your +apps in a widget file that could be installed on an AGL system. + +Specify what is the type of your targets that you want to be included in the +widget package with the property **LABELS**: + +Choose between: + +- **BINDING**: Shared library that be loaded by the AGL Application Framework +- **HTDOCS**: Root directory of a web app +- **DATA**: Resources used by your application +- **EXECUTABLE**: Entry point of your application executed by the AGL + Application Framework + +```cmake +SET_TARGET_PROPERTIES(${TARGET_NAME} + PREFIX "afb-" + LABELS "BINDING" + OUTPUT_NAME "file_output_name") +``` + +> **TIP** you should use the prefix _afb-_ with your **BINDING* targets which +> stand for **Application Framework Binding**. + +## More details: Typical project architecture A typical project architecture would be : @@ -86,21 +157,6 @@ A typical project architecture would be : | \ | \ | External dependencies libraries. This isn't to be used to include header file but build and link statically specifics libraries. | Library sources files. Can be a decompressed library archive file or project fork. | | \ | \ | A target to build, typically library, executable, etc. | -## Usage - -### Initialization - -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 -git submodule add https://gerrit.automotivelinux.org/gerrit/apps/app-templatesconf.d/app-templates conf.d/app-templates -mkdir conf.d/cmake -cp conf.d/app-templates/cmake/config.cmake.sample conf.d/cmake/config.cmake -``` - -Edit the copied config.cmake file to fit your needs. - ### Update app-templates submodule You may have some news bug fixes or features available from app-templates @@ -127,29 +183,6 @@ cd ../.. git commit -s conf.d/app-templates ``` -### Create CMake targets - -For each target part of your project, you need to use ***PROJECT_TARGET_ADD*** -to include this target to your project. - -Using it, make available the cmake variable ***TARGET_NAME*** until the next -***PROJECT_TARGET_ADD*** is invoked with a new target name. - -So, typical usage defining a target is: - -```cmake -PROJECT_TARGET_ADD(SuperExampleName) --> Adding target to your project - -add_executable/add_library(${TARGET_NAME}.... --> defining your target sources - -SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES.... --> fit target properties -for macros usage - -INSTALL(TARGETS ${TARGET_NAME}.... - -populate_widget() --> add target to widget tree depending upon target properties -``` - ### Build a widget #### config.xml.in file @@ -179,6 +212,14 @@ target type. As the type is not always specified for some custom targets, like an ***HTML5*** application, macros make the difference using ***LABELS*** property. +Choose between: + +- **BINDING**: Shared library that be loaded by the AGL Application Framework +- **HTDOCS**: Root directory of a web app +- **DATA**: Resources used by your application +- **EXECUTABLE**: Entry point of your application executed by the AGL + Application Framework + Example: ```cmake @@ -235,6 +276,44 @@ anything: project_subdirs_add("[0-9]-*") ``` +## Advanced customization + +### Including additionnals cmake files + +Advanced tuning is possible using addionnals cmake files that are included +automatically from some specifics locations. They are included in that order: + +- Project CMake files normaly located in _/conf.d/app-templates/cmake/cmake.d_ +- Home CMake files located in _$HOME/.config/app-templates/cmake.d_ +- System CMake files located in _/etc/app-templates/cmake.d_ + +CMake files has to be named using the following convention: `XX-***.cmake`, +where `XX` are numbers, `***` file name (ie. `99-my_customs.cmake`). + +So, saying that you should be aware that every normal cmake variables used at +project level could be overwrited by home or system located cmake files if +variables got the same name. Exceptions are cached variables set using +**CACHE** keyword: + +Example: + +```cmake +set(VARIABLE_NAME 'value string random' CACHE STRING 'docstring') +``` + +### Include customs templated scripts + +As well as for additionnals cmake files you can include your own templated +scripts that will be passed to cmake command `configure_file`. + +Just create your own script to the following directories: + +- Home location in _$HOME/.config/app-templates/scripts_ +- System location in _/etc/app-templates/scripts_ + +Scripts only needs to use the extension `.in` to be parsed and configured by +CMake command. + ## Autobuild script usage ### Generation @@ -275,4 +354,4 @@ Usage example: ```bash ./conf.d/autobuild/wgt/autobuild package DEST=/tmp -``` \ No newline at end of file +``` diff --git a/book.json b/book.json new file mode 100644 index 0000000..dafc6ae --- /dev/null +++ b/book.json @@ -0,0 +1,94 @@ +{ + "title": "CMake Application templates", + "subtitle": "Developer Documentation", + "description": "CMake templates used to build an AGL apps and widget", + "keywords": "AGL, Development, Iotbzh", + "author": "IoT.Bzh Team", + "website": "http://iot.bzh", + "published": "July 2017", + "version": "1.0", + + "gitbook": "3.2.2", + "root": "docs", + "pdf": { + "fontFamily": "Verdana", + "fontSize": 12, + "paperSize": "a4", + "pageBreaksBefore": "//h:div[@class=\"page-break\"]" + }, + "styles": { + "website": "resources/ebook.css", + "ebook": "resources/ebook.css", + "pdf": "resources/ebook.css" + }, + + "hidepageheaders": [2, 3], + "hidepagefooters": [2, 3], + + "plugins": [ + "regexplace" + ], + "pluginsConfig": { + "regexplace": { + "removeFirstPartsInSectionNumber": true, + "substitutes": [{ + "pattern": "", + "flags": "g", + "substitute": "
" + }, + { + "pattern": "", + "flags": "g", + "substitute": "
" + }, + { + "pattern": "", + "flags": "g", + "substitute": "
" + }, + { + "pattern": "", + "flags": "g", + "substitute": "
" + }, + { + "pattern": "", + "flags": "g", + "substitute": "
" + }, + { + "pattern": "", + "flags": "g", + "substitute": "
" + }, + { + "pattern": "!\\[(.*?)\\]\\((.*?)(?:\\s+\"(.*)\")?\\){0,}{caption=1([^\\}]*)}", + "flags": "gmi", + "substitute": "
\"$1\"
", + "decode": true + }, + { + "pattern": "]*) {0,}\/{0,}> {0,}{caption=1([^\\}]*)}", + "flags": "g", + "substitute": "
", + "decode": true + }, + { + "pattern": "
", + "flags": "g", + "substitute": "
Picture _PAGE_LEVEL_._INDEX_: $2
", + "store": { + "substitute": "Pic. _PAGE_LEVEL_._INDEX_ $2", + "variable_name": "pictures" + } + }, + { + "pattern": "]*)> {0,}{style {1,}([^}]*)}", + "flags": "g", + "substitute": "", + "decode": true + } + ] + } + } +} diff --git a/docs/0-Doc-Revisions.md b/docs/0-Doc-Revisions.md new file mode 100644 index 0000000..38b6e74 --- /dev/null +++ b/docs/0-Doc-Revisions.md @@ -0,0 +1,6 @@ +Document revisions +================== + +| Date | Version | Designation  | Author | +|-------------|---------|--------------------------------------|-------------------------| +| 4 Jul 2017 | 1.0 | Initial release | R. Forlot [ Iot.bzh ] | diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..39f9209 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,22 @@ +# Introduction + +This document explain how to use the CMake templates files and associated +files to ease developement of AGL application. + +
+
+
+
+
+ +| *Meta* | *Data* | +| -- | -- | +| **Title** | {{ config.title }} | +| **Author** | {{ config.author }} | +| **Description** | {{ config.description }} | +| **Keywords** | {{ config.keywords }} | +| **Language** | English | +| **Published** | Published {{ config.published }} as an electronic book | +| **Updated** | {{ gitbook.time }} | +| **Collection** | Open-source | +| **Website** | [{{ config.website }}]({{ config.website }}) | diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 0000000..f475678 --- /dev/null +++ b/docs/SUMMARY.md @@ -0,0 +1,10 @@ +# Summary + +* [Document revisions](0-Doc-Revisions.md) + +* [Developper guide](dev_guide/0_Abstract.md) + * [Quickstart](dev_guide/1_Quickstart.md) + * [Project architecture](dev_guide/2_project_architecture.md) + * [Advanced usage](dev_guide/3_advanced_usage.md) + * [Customization](dev_guide/4_advanced_customization.md) + * [Autobuild](dev_guide/5_autobuild.md) diff --git a/docs/_layouts/ebook/page.html b/docs/_layouts/ebook/page.html new file mode 100644 index 0000000..bf325e9 --- /dev/null +++ b/docs/_layouts/ebook/page.html @@ -0,0 +1,36 @@ +{% extends "layout.html" %} + +{% block title %}{{ page.title }}{% endblock %} +{% block description %}{{ page.description }}{% endblock %} + +{% block style %} + {### Include theme css before plugins css ###} + {% if not fileExists(config.styles.print) %} + {% if options.format %} + + {% else %} + + {% endif %} + {% endif %} + + {{ super() }} + + {### Custom stylesheets for the book ###} + + {% for type, style in config.styles %} + {% if fileExists(style) and (type == "ebook" or type == "print" or type == options.format) %} + + {% endif %} + {% endfor %} +{% endblock %} + +{% block body %} +
+ {% block page %} +

{{ page.title }}

+
+ {{ page.content|safe }} +
+ {% endblock %} +
+{% endblock %} diff --git a/docs/_layouts/ebook/pdf_footer.html b/docs/_layouts/ebook/pdf_footer.html new file mode 100644 index 0000000..679e562 --- /dev/null +++ b/docs/_layouts/ebook/pdf_footer.html @@ -0,0 +1,13 @@ +{% extends "./page.html" %} +{% block body %} + + + + +{% endblock %} diff --git a/docs/_layouts/ebook/pdf_header.html b/docs/_layouts/ebook/pdf_header.html new file mode 100644 index 0000000..ef49641 --- /dev/null +++ b/docs/_layouts/ebook/pdf_header.html @@ -0,0 +1,13 @@ +{% extends "./page.html" %} +{% block body %} +
+ IoT.Bzh + {{ config.title }} +
+ + + + +{% endblock %} \ No newline at end of file diff --git a/docs/_layouts/ebook/summary.html b/docs/_layouts/ebook/summary.html new file mode 100644 index 0000000..be328a4 --- /dev/null +++ b/docs/_layouts/ebook/summary.html @@ -0,0 +1,58 @@ +{% extends "./page.html" %} + +{% block title %}{{ "SUMMARY"|t }}{% endblock %} + +{% macro articles(_articles) %} + {% for article in _articles %} +
  • + + {% if article.path or article.url %} + {% if article.path %} + {{ article.title }} + {% else %} + {{ article.title }} + {% endif %} + {% else %} + {{ article.title }} + {% endif %} + {% if 1 %} + {{ article.level }} + {% endif %} + + {% if article.articles.length > 0 %} +
      + {{ articles(article.articles) }} +
    + {% endif %} +
    • + {% endfor %} +{% endmacro %} + +{% block page %} +
    +

    {{ "SUMMARY"|t }}

    +
      + {% for part in summary.parts %} + {% if part.title %} +
    1. +

      {{ part.title }}

      +
      2. + {% endif %} + {{ articles(part.articles) }} + + {% if not loop.last %} +
    2. + {% endif %} + {% endfor %} + + {% if glossary.path %} +
    3. + + {{ "GLOSSARY"|t }} + +
      4. + {% endif %} +
    +
    +{% endblock %} + diff --git a/docs/_layouts/layout.html b/docs/_layouts/layout.html new file mode 100644 index 0000000..3d5aca6 --- /dev/null +++ b/docs/_layouts/layout.html @@ -0,0 +1,28 @@ + + + + + + {% block title %}{{ config.title|d("GitBook", true) }}{% endblock %} + + + + {% if config.author %}{% endif %} + {% if config.isbn %}{% endif %} + {% block style %} + {% for resource in plugins.resources.css %} + {% if resource.url %} + + {% else %} + + {% endif %} + {% endfor %} + {% endblock %} + + {% block head %}{% endblock %} + + + {% block body %}{% endblock %} + {% block javascript %}{% endblock %} + + diff --git a/docs/cover.jpg b/docs/cover.jpg new file mode 100644 index 0000000..4e04b0c Binary files /dev/null and b/docs/cover.jpg differ diff --git a/docs/cover_small.jpg b/docs/cover_small.jpg new file mode 100644 index 0000000..315816b Binary files /dev/null and b/docs/cover_small.jpg differ diff --git a/docs/dev_guide/0_Abstract.md b/docs/dev_guide/0_Abstract.md new file mode 100644 index 0000000..a04cc87 --- /dev/null +++ b/docs/dev_guide/0_Abstract.md @@ -0,0 +1,21 @@ +# Developper Guide: use AGL CMake Templates + +## Abstract + +Files used to build an application, or binding, project with the +AGL Application Framework. + +To build your AGL project using these templates, you have to install +them within your project and adjust compilation option in `config.cmake`. +For technical reasons, you also have to specify **cmake** target in +sub CMakeLists.txt installed. Make a globbing search to find source files +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 usage samples here: + +- [helloworld-service](https://github.com/iotbzh/helloworld-service) +- [low-level-can-service](https://gerrit.automotivelinux.org/gerrit/apps/low-level-can-service) +- [high-level-viwi-service](https://github.com/iotbzh/high-level-viwi-service) +- [audio-binding](https://github.com/iotbzh/audio-binding) +- [unicens2-binding](https://github.com/iotbzh/unicens2-binding) diff --git a/docs/dev_guide/1_Quickstart.md b/docs/dev_guide/1_Quickstart.md new file mode 100644 index 0000000..fe11970 --- /dev/null +++ b/docs/dev_guide/1_Quickstart.md @@ -0,0 +1,71 @@ + +# Quickstart + +## Initialization + +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 +git submodule add https://gerrit.automotivelinux.org/gerrit/apps/app-templatesconf.d/app-templates conf.d/app-templates +mkdir conf.d/cmake +cp conf.d/app-templates/cmake/config.cmake.sample conf.d/cmake/config.cmake +``` + +Edit the copied config.cmake file to fit your needs. + +Now, create your top CMakeLists.txt file which include `config.cmake` file. + +An example is available in **app-templates** submodule that you can copy and +use: + +```bash +cp conf.d/app-templates/cmake/CMakeLists.txt CMakeLists.txt +``` + +## Create your CMake targets + +For each target part of your project, you need to use ***PROJECT_TARGET_ADD*** +to include this target to your project. + +Using it, make available the cmake variable ***TARGET_NAME*** until the next +***PROJECT_TARGET_ADD*** is invoked with a new target name. + +So, typical usage defining a target is: + +```cmake +PROJECT_TARGET_ADD(SuperExampleName) --> Adding target to your project + +add_executable/add_library(${TARGET_NAME}.... --> defining your target sources + +SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES.... --> fit target properties +for macros usage + +INSTALL(TARGETS ${TARGET_NAME}.... +``` + +## Targets PROPERTIES + +You should set properties on your targets that will be used to package your +apps in a widget file that could be installed on an AGL system. + +Specify what is the type of your targets that you want to be included in the +widget package with the property **LABELS**: + +Choose between: + +- **BINDING**: Shared library that be loaded by the AGL Application Framework +- **HTDOCS**: Root directory of a web app +- **DATA**: Resources used by your application +- **EXECUTABLE**: Entry point of your application executed by the AGL + Application Framework + +```cmake +SET_TARGET_PROPERTIES(${TARGET_NAME} + PREFIX "afb-" + LABELS "BINDING" + OUTPUT_NAME "file_output_name") +``` + +> **TIP** you should use the prefix _afb-_ with your **BINDING* targets which +> stand for **Application Framework Binding**. diff --git a/docs/dev_guide/2_project_architecture.md b/docs/dev_guide/2_project_architecture.md new file mode 100644 index 0000000..0cae607 --- /dev/null +++ b/docs/dev_guide/2_project_architecture.md @@ -0,0 +1,98 @@ +# Project architecture + +A typical project architecture would be : + +```tree + +│ +├── conf.d/ +│ ├── autobuild/ +│ │ ├── agl +│ │ │ └── autobuild +│ │ ├── linux +│ │ │ └── autobuild +│ │ └── windows +│ │ └── autobuild +│ ├── app-templates/ +│ │ ├── README.md +│ │ ├── autobuild/ +│ │ │ ├── agl +│ │ │ │ └── autobuild.in +│ │ │ ├── linux +│ │ │ │ └── autobuild.in +│ │ │ └── windows +│ │ │ └── autobuild.in +│ │ ├── cmake/ +│ │ │ ├── config.cmake.sample +│ │ │ ├── export.map +│ │ │ └── macros.cmake +│ │ ├── deb/ +│ │ │ └── config.deb.in +│ │ ├── rpm/ +│ │ │ └── config.spec.in +│ │ └── wgt/ +│ │ ├── config.xml.in +│ │ ├── config.xml.in.sample +│ │ ├── icon-default.png +│ │ ├── icon-html5.png +│ │ ├── icon-native.png +│ │ ├── icon-qml.png +│ │ └── icon-service.png +│ ├── packaging/ +│ │ ├── config.spec +│ │ └── config.deb +│ ├── cmake +│ │ └── config.cmake +│ └── wgt +│ └── config.xml.in +├── +├── +│ └── +├── +│ └── +└── + └── +``` + +| # | Parent | Description | +| - | -------| ----------- | +| \ | - | Path to your project. Hold master CMakeLists.txt and general files of your projects. | +| conf.d | \ | Holds needed files to build, install, debug, package an AGL app project | +| app-templates | conf.d | Git submodule to app-templates AGL repository which provides CMake helpers macros library, and build scripts. config.cmake is a copy of config.cmake.sample configured for the projects. SHOULD NOT BE MODIFIED MANUALLY !| +| autobuild | conf.d | Scripts generated from app-templates to build packages the same way for differents platforms.| +| cmake | conf.d | Contains at least config.cmake file modified from the sample provided in app-templates submodule. | +| wgt | conf.d | Contains at least config.xml.in template file modified from the sample provided in app-templates submodule for the needs of project (See config.xml.in.sample file for more details). | +| packaging | conf.d | Contains output files used to build packages. | +| \ | \ | External dependencies libraries. This isn't to be used to include header file but build and link statically specifics libraries. | Library sources files. Can be a decompressed library archive file or project fork. | +| \ | \ | A target to build, typically library, executable, etc. | + +## Manage app-templates submodule + +### Update + +You may have some news bug fixes or features available from app-templates +repository that you want. To update your submodule proceed like the following: + +```bash +git submodule update --remote +git commit -s conf.d/app-templates +``` + +This will update the submodule to the HEAD of master branch repository. Save +the modification by commiting it in your master git project. + +### Checkout submodule to a git tag + +You could just want to update at a specified repository tag or branch or commit +, here are the method to do so: + +```bash +cd conf.d/app-templates +# Choose one of the following depending what you want +git checkout +git checkout --detach +git checkout --detach +# Then commit +cd ../.. +git commit -s conf.d/app-templates +``` diff --git a/docs/dev_guide/3_advanced_usage.md b/docs/dev_guide/3_advanced_usage.md new file mode 100644 index 0000000..8994b41 --- /dev/null +++ b/docs/dev_guide/3_advanced_usage.md @@ -0,0 +1,92 @@ +# Build a widget + +## config.xml.in file + +To build a widget you need a _config.xml_ file describing what is your apps and +how Application Framework would launch it. This repo provide a simple default +file _config.xml.in_ that should work for simple application without +interactions with others bindings. + +It is recommanded that you use the sample one which is more complete. You can +find it at the same location under the name _config.xml.in.sample_ (stunning +isn't it). Just copy the sample file to your _conf.d/wgt_ directory and name it +_config.xml.in_, then edit it to fit your needs. + +> ***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 cmake templates 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 targets, like an ***HTML5*** +application, macros make the difference using ***LABELS*** property. + +Choose between: + +- **BINDING**: Shared library that be loaded by the AGL Application Framework +- **HTDOCS**: Root directory of a web app +- **DATA**: Resources used by your application +- **EXECUTABLE**: Entry point of your application executed by the AGL + Application Framework + +Example: + +```cmake +SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES + LABELS "HTDOCS" + OUTPUT_NAME dist.prod + ) +``` + +If your target output is not named as the ***TARGET_NAME***, you need to specify +***OUTPUT_NAME*** property that will be used by the ***populate_widget*** macro. + +Use the ***populate_widget*** macro as latest statement of your target +definition. Then at the end of your project definition you should use the macro +***build_widget*** that make an archive from the populated widget tree using the +`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: + +```cmake +PROJECT_TARGET_ADD(low-can-demo) +``` + +> ***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 + +This macro will search in all subfolder any `CMakeLists.txt` file. If found then +it will be added to your project. This could be use in an hybrid application by +example where the binding lay in a sub directory. + +Usage : + +```cmake +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]-*") +``` diff --git a/docs/dev_guide/4_advanced_customization.md b/docs/dev_guide/4_advanced_customization.md new file mode 100644 index 0000000..796232f --- /dev/null +++ b/docs/dev_guide/4_advanced_customization.md @@ -0,0 +1,37 @@ +# Advanced customization + +## Including additionnals cmake files + +Advanced tuning is possible using addionnals cmake files that are included +automatically from some specifics locations. They are included in that order: + +- Project CMake files normaly located in _/conf.d/app-templates/cmake/cmake.d_ +- Home CMake files located in _$HOME/.config/app-templates/cmake.d_ +- System CMake files located in _/etc/app-templates/cmake.d_ + +CMake files has to be named using the following convention: `XX-***.cmake`, +where `XX` are numbers, `***` file name (ie. `99-my_customs.cmake`). + +So, saying that you should be aware that every normal cmake variables used at +project level could be overwrited by home or system located cmake files if +variables got the same name. Exceptions are cached variables set using +**CACHE** keyword: + +Example: + +```cmake +set(VARIABLE_NAME 'value string random' CACHE STRING 'docstring') +``` + +## Include customs templated scripts + +As well as for additionnals cmake files you can include your own templated +scripts that will be passed to cmake command `configure_file`. + +Just create your own script to the following directories: + +- Home location in _$HOME/.config/app-templates/scripts_ +- System location in _/etc/app-templates/scripts_ + +Scripts only needs to use the extension `.in` to be parsed and configured by +CMake command. diff --git a/docs/dev_guide/5_autobuild.md b/docs/dev_guide/5_autobuild.md new file mode 100644 index 0000000..fe1c63d --- /dev/null +++ b/docs/dev_guide/5_autobuild.md @@ -0,0 +1,41 @@ +# Autobuild script usage + +## Generation + +To be integrated in the Yocto build workflow you have to generate `autobuild` +scripts using _autobuild_ target. + +To generate those scripts proceeds: + +```bash +mkdir -p build +cd build +cmake .. && make autobuild +``` + +You should see _conf.d/autobuild/agl/autobuild_ file now. + +## Available targets + +Here are the available targets available from _autobuild_ scripts: + +- **clean** : clean build directory from object file and targets results. +- **distclean** : delete build directory +- **configure** : generate project Makefile from CMakeLists.txt files. +- **build** : compile all project targets. +- **package** : build and output a wgt package. + +You can specify variables that modify the behavior of compilation using +the following variables: + +- **CONFIGURE_ARGS** : Variable used at **configure** time. +- **BUILD_ARGS** : Variable used at **build** time. +- **DEST** : Directory where to output ***wgt*** file. + +Variable as to be in CMake format. (ie: BUILD_ARGS="-DC_FLAGS='-g -O2'") + +Usage example: + +```bash +./conf.d/autobuild/wgt/autobuild package DEST=/tmp +``` diff --git a/docs/dev_guide/pictures/iotbzh_logo_small.png b/docs/dev_guide/pictures/iotbzh_logo_small.png new file mode 100644 index 0000000..6a98c60 Binary files /dev/null and b/docs/dev_guide/pictures/iotbzh_logo_small.png differ diff --git a/docs/resources/cover.svg b/docs/resources/cover.svg new file mode 100644 index 0000000..6726de7 --- /dev/null +++ b/docs/resources/cover.svg @@ -0,0 +1,210 @@ + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + {title} + + {subtitle} + + {version} {date} + diff --git a/docs/resources/ebook.css b/docs/resources/ebook.css new file mode 100644 index 0000000..39f126c --- /dev/null +++ b/docs/resources/ebook.css @@ -0,0 +1,386 @@ +/* IoT.Bzh theaming */ + +h1 { + color: #330066; + border-bottom: 2px solid #330066; +} + +h2 { + color: #330066; +} + +h3 { + color: #330066; +} + +h4 { + color: #330066; +} + + +/* GENERAL ELEMENTS */ + +/* clear both */ + +.clear { + clear: both; +} + +.section> :last-child { + margin-bottom: 0 !important; +} + +.section> :first-child { + margin-top: 0 !important; +} + + +/* SPECIAL ELEMENTS */ + + +/* page break always after element on pdf/print definition */ + +div.pagebreak { + page-break-after: always; +} + + +/* no page break inside element on pdf/print definition */ + +div.nopb { + page-break-inside: avoid !important; + margin: 4px 0 4px 0; +} + + +/* note blocks */ + +div.note { + background: #FCF8E3 none repeat scroll 0% 0%; + color: #8A6D3B; + padding: 15px; + margin-bottom: 10px; + border-bottom: 5px solid #DDD; + border-color: #FAEBCC; + page-break-inside: avoid; +} + +div.note p { + padding-bottom: 0; + margin-bottom: 0; +} + + +/* images, figures and captions */ + +p img { + /* center all images */ + display: block; + margin: 0 auto; + padding: 10px 0; +} + +figure { + margin: 1.0em 0px; + padding: 10px 0; + text-align: center; + page-break-inside: avoid; + display: block; +} + +figure img { + display: block; + margin: 0 auto; +} + +figcaption { + clear: left; + margin: 1.0em 0 0 0; + text-align: center; + font-style: italic; + line-height: 1.5em; + font-size: 80%; + color: #666; + display: block; +} + +.page .section p img { + margin-top: 10px; +} + + +/* ul, ol list margin fix */ + +.page .section ol, +.page .section ul { + margin-bottom: 10px; +} + + +/* blockquotes */ + +.page .section blockquote { + margin: 0 0 0 5%; + font-style: italic; +} + + +/* PAGE SPECIFIC */ + + +/* set summary page to right side of the paper */ + +.page .toc h1 { + page-break-before: right; +} + +.page .section.toc { + page-break-inside: always; +} + +/* table headers */ + +div#README\.md table { + margin-top: 30px; + font-size: 95%; +} + +div#README\.md table thead { + display: none; +} + + + +/* CITATION AND IMAGES */ + + +/* math image styles */ + +.page .section p img.svg, +.page .section p img.png { + margin-top: 0px; + margin-bottom: -2px; +} + +.page .section p img.math { + vertical-align: middle; + height: auto; + width: auto; + margin-top: -4px; + max-height: 15px; +} + +.page .section p img.math.line1 { + margin-top: -7px; + max-height: 19px; +} + +.page .section p img.math.line2 { + margin-top: -1px; + max-height: 30px; +} + + +/* credits page */ + +.page .section ul.pictures { + margin-left: -30px; +} + +.page .section ul.pictures li { + list-style: outside none none; +} + +.page .section ul.pictures li a { + float: left; +} + +.page .section ul.pictures li span { + display: block; + margin-left: 100px; +} + + + +/* sub and super script */ + +.page .section sub { + font-size: 80%; + margin-left: 1px; +} + + +/* citations and references */ + +.page .section sup { + margin-left: -1px; + margin-right: 2px; + font-size: 80%; +} + +.page .section sup:before { + content: " "; +} + +.page .section ul.citations, +.page .section ul.references { + margin-left: -30px; +} + + +.page .section ul.citations li:nth-child(1) { + margin-top: 20px; + padding-top: 20px; + border-top: 1px solid #BBB; +} + +.page .section ul.citations li, +.page .section ul.references li { + list-style: outside none none; +} + +.page .section ul.citations li { + font-size: 80%; +} + +.page .section ul.citations li>span:nth-child(1), +.page .section ul.references li>span:nth-child(1) { + display: block; + float: left; + text-align: left; + width: 70px +} + +.page .section ul.citations li>span:nth-child(1) { + width: 50px +} + +.page .section ul.references li div { + margin-left: 70px; +} + +.page .section ul.citations li div { + margin-left: 50px; +} + +.page .section a[href="#"], +.page .section a[href="#"]:link, +.page .section a[href="#"]:visited, +.page .section a[href="#"]:hover, +.page .section a[href="#"]:focus { + text-decoration: none; + color: inherit; + cursor: text; + font-style: italic; +} + + +/* self referential footnotes */ + +.page .section div[type="selfref"] a[href="#"], +.page .section div[type="selfref"] a[href="#"]:link, +.page .section div[type="selfref"] a[href="#"]:visited, +.page .section div[type="selfref"] a[href="#"]:hover, +.page .section div[type="selfref"] a[href="#"]:focus { + font-style: normal; +} + +.page .section div[type="selfref"] span:nth-child(1) { + display: none; +} + + +/* page break always after element on pdf/print definition */ + +div.page-break { + page-break-inside: always; +} + +div.page-break:before { + content: ' '; +} + + +/* no page break inside element on pdf/print definition */ + +div.nopb { + page-break-inside: avoid; +} + +/* justify text */ +p { + text-align: justify; +} + +/* page header and footer */ + +.pdf-footer, +.pdf-header { + margin-top: 20px; + color: #aaa; +} + +.pdf-header .header-left { + float: left; + margin-left: 2em; + margin-right: auto; +} + +.pdf-header .header-right { + display: table; + margin-left: auto; + margin-right: 2em; +} + +.pdf-footer .sub { + padding-top: 8px; + font-size: 70%; +} + +.pdf-header .sub { + padding-top: 2px; + font-size: 70%; +} + +.pdf-footer { + padding-top: 10px; + border-top: 1px solid #eee; +} + +.pdf-footer .footer-left { + float: left; + margin-left: 2em; + margin-right: auto; +} + +.pdf-footer .footer-center { + display: table; + margin-left: auto; + margin-right: auto; +} + +.pdf-footer .footer-right { + float: right; + margin-left: auto; + margin-right: 2em; +} + +.pdf-header { + padding-bottom: 10px; + border-bottom: 1px solid #eee; +} + +.pdf-header .header-pages-count { + float: right; + text-align: right; +} + +.pdf-header .header-pages-count a, +.pdf-header .header-pages-count a:visited, +.pdf-header .header-pages-count a:active, +.pdf-header .header-pages-count a:focus, +.pdf-header .header-pages-count a:link { + text-decoration: none; + color: #aaa; + cursor: text; +} diff --git a/docs/resources/make_cover.sh b/docs/resources/make_cover.sh new file mode 100755 index 0000000..1026ecb --- /dev/null +++ b/docs/resources/make_cover.sh @@ -0,0 +1,27 @@ +#!/bin/bash +DOCS_DIR=$(cd $(dirname $0)/.. && pwd) +BOOKFILE=$DOCS_DIR/../book.json + +TITLE=$(grep '"title":' $BOOKFILE | cut -d'"' -f 4) +SUBTITLE=$(grep '"subtitle":' $BOOKFILE | cut -d'"' -f 4) +VERSION="Version $(grep '"version":' $BOOKFILE | cut -d'"' -f 4)" +DATE=$(grep '"published":' $BOOKFILE | cut -d'"' -f 4) + +[ -z "$TITLE" ] && { echo "Error TITLE not set!" ; exit 1; } +[ -z "$VERSION" ] && { echo "Error VERSION not set!" ; exit 1; } +[ -z "$DATE" ] && { echo "Error DATE not set!" ; exit 1; } + + +cat $(dirname $0)/cover.svg | sed -e "s/{title}/$TITLE/g" \ + -e "s/font-size:87.5px/font-size:54px/g" \ + -e "s/{subtitle}/$SUBTITLE/g" \ + -e "s/font-size:62.5px/font-size:40px/g" \ + -e "s/{version}/$VERSION/g" \ + -e "s/{date}/$DATE/g" \ + > /tmp/cover.svg + +# use imagemagick convert tool (cover size must be 1800x2360) +convert -resize "1600x2160!" -border 100 -bordercolor white -background white \ + -flatten -quality 100 /tmp/cover.svg $DOCS_DIR/cover.jpg + +convert -resize "200x262!" $DOCS_DIR/cover.jpg $DOCS_DIR/cover_small.jpg diff --git a/gendocs.sh b/gendocs.sh new file mode 100755 index 0000000..ea9400a --- /dev/null +++ b/gendocs.sh @@ -0,0 +1,79 @@ +#!/bin/bash + +OUTFILENAME="Gitbook-Iotbzh-template" + +SCRIPT=$(basename $BASH_SOURCE) + +function usage() { + cat <&2 +Usage: $SCRIPT [options] [pdf|serve|doxygen] + +Options: + --debug + enable debug when generating pdf or html documentation + -d|--dry + dry run + -h|--help + get this help + +Example: + $SCRIPT pdf + +EOF + exit 1 +} + +function info() { + echo "$@" >&2 +} + +#default values +DEBUG_FLAG="" +DRY="" +DO_ACTION="" +OUT_DIR=./build + +[[ $? != 0 ]] && usage +while [ $# -gt 0 ]; do + case "$1" in + --debug) DEBUG_FLAG="--log=debug --debug";; + -d|--dry) DRY=echo;; + -h|--help) usage;; + pdf | serve | doxygen) DO_ACTION=$1;; + --) break;; + esac + shift +done + +cd $(dirname $0) +ROOTDIR=`pwd -P` + +# Create out dir if needed +[ -d $OUT_DIR ] || mkdir -p $OUT_DIR + +if [ "$DO_ACTION" = "pdf" -o "$DO_ACTION" = "serve" ]; then + GITBOOK=`which gitbook` + [ "$?" = "1" ] && { echo "You must install gitbook first, using: sudo npm install -g gitbook-cli"; exit 1; } + + EBCONV=`which ebook-convert` + [ "$?" = "1" ] && { echo "You must install calibre first, using: 'sudo apt install calibre' or refer to https://calibre-ebook.com/download"; exit 1; } + + if [ "$DO_ACTION" = "pdf" ]; then + + # Update cover when book.json has been changed + [[ $ROOTDIR/book.json -nt $ROOTDIR/docs/cover.jpg ]] && { echo "Update cover files"; $ROOTDIR/docs/resources/make_cover.sh || exit 1; } + + OUTFILE=$OUT_DIR/$OUTFILENAME.pdf + $DRY $GITBOOK pdf $ROOTDIR $OUTFILE $DEBUG_FLAG + [ "$?" = "0" ] && echo "PDF has been successfully generated in $OUTFILE" + else + $DRY $GITBOOK serve $DEBUG_FLAG + fi + +elif [ "$DO_ACTION" = "doxygen" ]; then + $DRY cd $OUT_DIR && cmake .. && make doxygen $ROOTDIR/Doxyfile + +else + echo "Unknown action !" + usage +fi