Developing External Native Apps

External native apps are 3rd party native apps that must be installed on the webOS target device.

This page describes the steps to develop an external native app using Sample Code Repository and CLI. For detailed information on the CLI commands used in this tutorial, see CLI commands.

Developing an external native app requires the following steps:

• Before You Begin
• Step 1: Implement a Native App
• Step 2: Configure the Native App
• Step 3: Build the Native App
• Step 4: Package the Native App
• Step 5: Install the Native App
• Step 6: Launch the Native App

Before you begin

• Make sure you have completed the steps in Native Development Kit Setup.

• Download the sample repository, and move into samples/native-apps/external/com.sample.waylandegl directory.

  $ git clone https://github.com/webosose/samples
  $ cd samples/native-apps/external/com.sample.waylandegl
  

The directory structure of com.sample.waylandegl must be as follows:

native-apps/external/com.sample.waylandegl/
├── src/
│   └── wayland_egl.c
├── appinfo.json
├── CMakeLists.txt
├── icon.png
└── README.md

Step 1: Implement a Native App

Source Code

Design and implement the source code for native app.

The sample codes will display a yellow screen on your target device. In this section, we will briefly explain webOS specific parts in src/wayland_egl.c.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

#include <wayland-egl.h>
...
struct wl_webos_shell *g_pstWebOSShell = NULL;
struct wl_webos_shell_surface *g_pstWebosShellSurface = NULL;
...

// Please see wayland-webos-shell-client-protocol.h file for webOS specific wayland protocol
g_pstWebosShellSurface = wl_webos_shell_get_shell_surface(g_pstWebOSShell, g_pstSurface);
if (g_pstWebosShellSurface == NULL)
{
    fprintf(stderr, "Can't create webos shell surface\n");
    exit(1);
}
wl_webos_shell_surface_add_listener(g_pstWebosShellSurface, &s_pstWebosShellListener, g_pstDisplay);
wl_webos_shell_surface_set_property(g_pstWebosShellSurface, "appId", (getenv("APP_ID") ? getenv("APP_ID") : "com.sample.waylandegl"));
// for secondary display, set the last parameter as 1
wl_webos_shell_surface_set_property(g_pstWebosShellSurface, "displayAffinity", (getenv("DISPLAY_ID") ? getenv("DISPLAY_ID") : "0"));
...

A brief explanation of the above file:

• Line(1) : Include wayland-webos-shell-client-protocol.h header file which has wl_webos_shell and wl_webos_shell_surface structure.
• Line(5~6) : Declare wl_webos_shell and wl_webos_shell_surface structure which are the webOS specific extension of wl_shell and wl_shell_surface.
• Line(11~18) : Create a webOS shell surface for an existing surface and add the listener to receive events.
• Line(20) : Set the property related to display. If you set the last parameter to 1, the sample app will be displayed on a secondary display. To set up the secondary display, see Dual-Display Setup.

For detailed information on the webOS-specific protocol extension, visit webOS OSE GitHub.

Step 2: Configure the Native App

This section describes how to prepare the configuration files required to build and test the native app.

appinfo.json

Apps are required to have metadata before they can be packaged. This metadata is stored in a file called appinfo.json, which is used by the webOS device to identify the app, its icon, and other information that is needed to launch the app.

1
2
3
4
5
6
7
8
9

{
    "id": "com.sample.waylandegl",
    "version": "0.0.1",
    "vendor": "My Company",
    "type": "native",
    "main": "wayland_egl",
    "title": "wayland_egl",
    "icon": "icon.png"
}

A brief explanation of the above file:

• Line(2) : The ID for the app.
• Line(5) : The type of the native app.
• Line(6) : The executable file name.
• Line(7) : The title to be shown on the Launchpad and App Bar.
• Line(8) : The icon to be shown on the Launchpad. Make sure the icon file is available in the project root directory. You can use your own icon.png (80*80) file or attached icon.png.

For more details, see appinfo.json.

CMakeLists.txt

CMakeLists.txt file is used by CMake to generate the Makefile to build the project. This file specifies the source, header, and UI files included in the project.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

cmake_minimum_required(VERSION 2.8.7)
project(wayland_egl C CXX)

include_directories(${CMAKE_SOURCE_DIR})
include_directories(${CMAKE_SOURCE_DIR}/src)
include_directories(${CMAKE_SOURCE_DIR}/include)

include(FindPkgConfig)

pkg_check_modules(WLCLIENT REQUIRED wayland-webos-client)
include_directories(${WLCLIENT_INCLUDE_DIRS})

pkg_check_modules(WLEGL REQUIRED wayland-egl)
include_directories(${WLEGL_INCLUDE_DIRS})

pkg_check_modules(EGL REQUIRED egl)
include_directories(${EGL_INCLUDE_DIRS})

pkg_check_modules(GLESV2 REQUIRED glesv2)
include_directories(${GLESV2_INCLUDE_DIRS})

set(BIN_NAME wayland_egl)

set(SRC_LIST
        ${CMAKE_SOURCE_DIR}/src/wayland_egl.c
)

set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_SOURCE_DIR}/pkg_$ENV{OECORE_TARGET_ARCH}/")
add_executable(${BIN_NAME} ${SRC_LIST})
set_target_properties(${BIN_NAME} PROPERTIES LINKER_LANGUAGE C)

target_link_libraries (${BIN_NAME}
        ${WLCLIENT_LDFLAGS}
        ${WLEGL_LDFLAGS}
        ${EGL_LDFLAGS}
        ${GLESV2_LDFLAGS}
)

# copy appinfo.json file to output folder
if(EXISTS "${CMAKE_SOURCE_DIR}/appinfo.json")
    file(COPY "${CMAKE_SOURCE_DIR}/appinfo.json" DESTINATION ${CMAKE_RUNTIME_OUTPUT_DIRECTORY})
else()
    MESSAGE( "'appinfo.json' file was not found !!")
endif()

# copy icon.png file to output folder
if(EXISTS "${CMAKE_SOURCE_DIR}/icon.png")
    file(COPY "${CMAKE_SOURCE_DIR}/icon.png" DESTINATION ${CMAKE_RUNTIME_OUTPUT_DIRECTORY})
else()
    MESSAGE( "'icon.png' file was not found !!")
endif()

A brief explanation of the above file:

• Line(1) : Set the minimum CMake version.
• Line(2) : Set the project name and programming language.
• Line(4~20) : Add the directories that contain the header files.
• Line(22~29) : Set the name of result binary file and source files to be built.
• Line(30) : Set the language for linker.
• Line(32~37) : Specify the libraries to be used.
• Line(40~51) : Copy the appinfo.json and icon.png files to the output folder.

For more details, see CMake Reference Documentation.

Step 3: Build the Native App

You are now ready to build the native app. Perform the following steps:

1. Go to your project directory (com.sample.waylandegl).

2. Create a build directory and go to the directory.

   $ mkdir BUILD
   $ cd BUILD
   

3. Execute the cmake command. Then execute the make command. A pkg_<YOUR_ARCHITECTURE> directory will be created in your project folder (com.sample.waylandegl).

   $ cmake ..
   $ make
   

   Note
   In the name of the created directory, <YOUR_ARCHITECTURE> depends on your build machine’s architecture.

Step 4: Package the Native App

After building the native app, it must be packaged as an IPK file. Make sure the appinfo.json file is available, because it is required when packaging an external native app for webOS OSE.

To package the native app, use the ares-package command. The packaged file is generated in the current directory.

$ cd ..
$ ares-package pkg_arm64

In the above command, pkg_arm64 is the native app directory. You can use an absolute or relative path. Also, you can package the app with a service. For more details on using ares-package, see ares-package.

Step 5: Install the Native App

To install the native app on the target device, execute the following command:

$ ares-install ./com.sample.waylandegl_0.0.1_aarch64.ipk -d <TARGET_DEVICE>

In the above command:

• <TARGET_DEVICE> is the name of the target device.
• ./com.sample.waylandegl_0.0.1_aarch64.ipk is the name of the IPK file that is generated after packaging the app in the previous step.

If the installation is successful, a Success message will appear.

To verify the installation, check if the native app ID (in this case, com.sample.waylandegl) is available in the output of the following command:

$ ares-install --device <TARGET_DEVICE> --list

To remove the app from the device, use the ares-install command as follows:

$ ares-install --device <TARGET_DEVICE> --remove com.sample.waylandegl

Step 6: Launch the Native App

Using the CLI

To launch the native app using the CLI, execute the following command:

$ ares-launch --device <TARGET_DEVICE> com.sample.waylandegl

In the above command:

• <TARGET_DEVICE> is the name of the target device. This is the same device on which the app was installed in the previous step.
• com.sample.waylandegl is the app ID that is available after installing the app.

After executing the above command, check the target device to see if the app is running.

To close the app, use the ares-launch command as follows:

$ ares-launch --device <TARGET_DEVICE> --close com.sample.waylandegl

Using the Target Device

To launch the native app using the target device, you need to display the Launchpad first.

1. Drag the mouse cursor upward from the bottom of the screen (or swipe up from the bottom of the screen if you’re using a touch display).

2. Click the Launchpad icon.

   

3. After the Launchpad is displayed, click the app icon.