docs/dev_guide/1_Quickstart.md

   1 # Quickstart
   2
   3 ## Initialization
   4
   5 To use these templates files on your project just install the reference files using
   6 **git submodule** then use `config.cmake` file to configure your project specificities :
   7
   8 ```bash
   9 git submodule add https://gerrit.automotivelinux.org/gerrit/p/apps/app-templates.git conf.d/app-templates
  10 mkdir conf.d/cmake
  11 cp conf.d/app-templates/samples.d/config.cmake.sample conf.d/cmake/config.cmake
  12 ```
  13
  14 Edit the copied config.cmake file to fit your needs.
  15
  16 Now, create your top CMakeLists.txt file which include `config.cmake` file.
  17
  18 An example is available in **app-templates** submodule that you can copy and
  19 use:
  20
  21 ```bash
  22 cp conf.d/app-templates/samples.d/CMakeLists.txt.sample CMakeLists.txt
  23 ```
  24
  25 ## Create your CMake targets
  26
  27 For each target part of your project, you need to use ***PROJECT_TARGET_ADD***
  28 to include this target to your project.
  29
  30 Using it, make available the cmake variable ***TARGET_NAME*** until the next
  31 ***PROJECT_TARGET_ADD*** is invoked with a new target name.
  32
  33 So, typical usage defining a target is:
  34
  35 ```cmake
  36 PROJECT_TARGET_ADD(SuperExampleName) --> Adding target to your project
  37
  38 add_executable/add_library(${TARGET_NAME}.... --> defining your target sources
  39
  40 SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES.... --> fit target properties
  41 for macros usage
  42
  43 INSTALL(TARGETS ${TARGET_NAME}....
  44 ```
  45
  46 ## Targets PROPERTIES
  47
  48 You should set properties on your targets that will be used to package your
  49 apps in a widget file that could be installed on an AGL system.
  50
  51 Specify what is the type of your targets that you want to be included in the
  52 widget package with the property **LABELS**:
  53
  54 Choose between:
  55
  56 - **BINDING**: Shared library that be loaded by the AGL Application Framework
  57 - **BINDINGV2**: Shared library that be loaded by the AGL Application Framework
  58  This has to be accompagnied with a JSON file named like the
  59  *${OUTPUT_NAME}-apidef* of the target that describe the API with OpenAPI
  60  syntax (e.g: *mybinding-apidef*).
  61  Or Alternatively, you can choose the name, without the extension, using macro
  62  **set_openapi_filename**. If you use C++, you have to set **PROJECT_LANGUAGES**
  63  with *CXX*.
  64 - **BINDINGV3**: Shared library that be loaded by the AGL Application Framework
  65  This has to be accompagnied with a JSON file named like the
  66  *${OUTPUT_NAME}-apidef* of the target that describe the API with OpenAPI
  67  syntax (e.g: *mybinding-apidef*).
  68  Or Alternatively, you can choose the name, without the extension, using macro
  69  **set_openapi_filename**. If you use C++, you have to set **PROJECT_LANGUAGES**
  70  with *CXX*.
  71 - **PLUGIN**: Shared library meant to be used as a binding plugin. Binding
  72  would load it as a plugin to extend its functionnalities. It should be named
  73  with a special extension that you choose with SUFFIX cmake target property or
  74  it'd be **.ctlso** by default.
  75 - **HTDOCS**: Root directory of a web app. This target has to build its
  76  directory and puts its files in the ${CMAKE_CURRENT_BINARY_DIR}/${TARGET_NAME}
  77 - **DATA**: Resources used by your application. This target has to build its
  78  directory and puts its files in the ${CMAKE_CURRENT_BINARY_DIR}/${TARGET_NAME}
  79 - **EXECUTABLE**: Entry point of your application executed by the AGL
  80  Application Framework
  81 - **LIBRARY**: An external 3rd party library bundled with the binding for its
  82  own purpose because platform doesn't provide it.
  83 - **BINDING-CONFIG**: Any files used as configuration by your binding.
  84
  85 > **TIP** you should use the prefix _afb-_ with your **BINDING* targets which
  86 > stand for **Application Framework Binding**.
  87
  88 ```cmake
  89 SET_TARGET_PROPERTIES(${TARGET_NAME}
  90         PREFIX "afb-"
  91         LABELS "BINDINGV3"
  92         OUTPUT_NAME "file_output_name")
  93 ```
  94
  95 > **NOTE**: You doesn't need to specify an **INSTALL** command for these
  96 > targets. This is already handle by template and will be installed in the
  97 > following path : **${CMAKE_INSTALL_PREFIX}/${PROJECT_NAME}**