Roku Server Builds

The steps to build a Roku app depend on whether you are developing a You.i React Native app or a C++ app, and whether you want a Debug or Release version of the app.

Furthermore, Roku apps have both a cloud server portion containing the app logic and a Roku client portion that is on the Roku device. This topic covers building the cloud server portion only. For instructions on building the Roku client portion, see Update Using the Build Script.

Cloud Solution app development can occur on macOS or Linux. If you use Linux for Cloud Solution app development, Ubuntu 18.04 is required for React Native and C++ projects.

Application Versioning

For feature parity and maximum compatibility, it’s important that your Roku client and server applications use the same release of You.i Platform. Starting in release 5.6, You.i Platform enforces a shared Engine version between client and server components.

Add a version exception

While it’s not recommended, there may be cases where you need to allow a mismatch between the Engine versions used by your client and server applications. Test your application very well if using this exception mechanism; differences in the Engine version may cause unexpected behavior.

To allow a server version greater than the client version, find or create /AE/assets/json/default/serverConfig.json in your project folder. Add the Engine version of your client as shown below. In this example, if the server is upgraded to 5.7.0, client applications can continue to use version 5.6.0. Note: Connections are always accepted if both are using the same version of You.i Platform.

// serverConfig.json
{
  "serverVersionOverride" : "5.6.0"
}

If you’re updating your client but not your server, you can add client_version_override to the client manifest file, specifying the Engine version of the server application your client is expecting to connect to. For example, a client built with Engine version 5.8 can connect to a server with version 5.7 if the following is added to the client manifest file:

# manifest
# other config values...
analytics_providers=ConvivaAnalytics

client_version_override=5.7.0

Once you fix the mismatch, simply remove these lines from serverConfig.json and the client manifest file. Also note that clients or servers built with You.i Platform 5.6 or higher don’t work (even with an exception set) with versions 5.5 and lower of the Engine.

Building You.i React Native Roku Apps - Debug Version

For Debug builds, you can build from a Mac or Linux platform. You.i TV recommends that you use the osx build target for ongoing development builds.

  1. If using the sample application, copy the /Users/<username>/youiengine/<version>/samples/RNSampleApp/ folder to a location outside the youiengine directory; for example:

    cd /Users/<username>/MyApp

  2. Install dependencies for the project:

    yarn install

  3. Build your debug application by running the following command from your project’s youi folder (substitute -p linux if on linux):

    youi-tv build -p osx -d YI_BUILD_CLOUD_SERVER=ON
    

If the build fails, read and analyze the failure messages to identify the cause. Refer to Roku App Build Issues for possible corrective measures. For other build options, see youi-tv build.

Launch the App

Once the app builds successfully, do the following steps to launch the app.

  1. Use the Metro Bundler ( yarn server), open a new Terminal, then do:

    cd <your application folder> e.g., cd MyApp

    yarn start

    The yarn server starts. Look for the following to appear in the window:

    Welcome to React Native! Learn once, write anywhere

    To stop the Metro Bundler, press Ctrl + C.

  2. For Mac, you can launch the app from MyApp/youi/build/osx/Debug/MyApp or you can use Xcode as follows:

    1. Navigate to the directory containing the IDE project. Enter:

      cd ~/MyApp/youi/build/osx

    2. Start Xcode and open the project. In the Terminal window enter:

      open MyApp.xcodeproj

      Xcode opens the project and indexes the project files.

    3. Ensure the MyApp target is selected from the dropdown menu to the right of the Play button.

      Image

    4. Press the Play button in the top-left corner or press Cmd-R to run the app. You may be prompted to enable Developer mode.

      The app displays a blank monochromatic screen while it waits to communicate with a client running on a Roku device.

    5. Prepare the Roku device for local testing as described in Roku Client Builds.

    6. Launch the app installed on the Roku device.

      The app plays simultaneously on a simulator on your development platform and on the test Roku device. Use the Roku controls to interact with the app. Observe the result of your changes.

  3. For Linux, navigate to the build/linux/Debug/bin subdirectory and run ./MyApp.

Tip You can use the following run time argument for debugging during development:

  • -n1: Use this argument at run time either with XCode or with the app’s executable, as in ./MyApp -n1, to see all the logs and messages on your screen instead of the app’s user interface. You can only see the messages or logs when the app connects to Roku client.
  • -i: Use this argument at run time to launch the app immediately for debugging without the Roku client, as in ./MyApp -i.

Building You.i React Native Roku Apps: Release Version

Production apps are intended to be sent for certification or deployed to the general public. For details, see Deploying Roku Apps. You need to build the Release version of the app for the linux platform target. The procedure is similar to building the Debug version, but requires the extra -c Release argument.

Use the following checklist to ensure you have a correct build environment for the Release version of the app.

  1. The correct versions of CMake and GCC (Linux) are installed installed. See Hardware and Software Specifications.

  2. The following environment variables are configured (see Configure Environment Variables):
    • YI_CLOUD_SERVER_PORT
    • AWS_ACCESS_KEY_ID
    • AWS_SECRET_ACCESS_KEY
    • YI_SCENEGRAPH_EXPORT_BUCKET
    • YI_SCENEGRAPH_EXPORT_DIR
    • YI_CLOUD_S3_TAG
  3. Confirm your Linux build environment is correctly configured by building a You.i Platform sample app from the You.i Platform package on Linux. See Building a You.i React Native Sample App.

  4. Build the Release version of the app. See Release Build Procedure - You.i C++ Roku.

Release Build Procedure: You.i React Native Roku

This procedure assumes the following:

To build your app, do following steps from a Linux computer:

  1. For example, run the following command from your project’s youi folder:
youi-tv build -p linux -d YI_BUILD_CLOUD_SERVER=ON -c Release

If you want to deploy the production version of your Cloud Solution app on AWS, you must use the --local build argument. For more details, see the Build Options section.

Your application is generated in the build/linux/Release/bin subdirectory. For details, see Building apps.

Tip You can use the following run time arguments for debugging during development:

  • -n1: Use this argument at run time either with XCode or with the app’s executable, as in ./MyApp -n1, to see all the logs and messages on your screen instead of the app’s user interface. You can only see the messages or logs when the app connects to Roku client.
  • -m: Use this argument to enable longer node names for debugging in the Release mode.

If the build fails, read and analyze the failure messages to identify the cause. Refer to Roku App Build Issues for possible corrective measures.

Building C++ Roku Apps: Debug Version

For Debug builds, you can build from a Mac or Linux platform. You.i TV recommends that you use the osx build target for ongoing development builds.

Debug Build Procedure: You.i Engine C++ Roku

To build your app, do following steps from your project’s youi folder (substitute -p linux if on linux):

youi-tv build -p osx -d <my_CloudSDK_option>

Substitute <my_CloudSDK_option> for the option you created when you customized your project CMake file. See Step 6 in Additional Developer Setup Tasks and Updating your Legacy C++ App’s Build Files. The following are examples of possible commands depending on your implementation of the CMake file:

  • youi-tv build -p osx -d YI_BUILD_CLOUD_SERVER=ON, or
  • youi-tv build -p osx -d YI_CONFIG_PATH=config/config-osx.txt

The app is generated in the build/osx/Debug or the build/linux/Debug/bin subdirectory. If the build fails, read and analyze the failure messages to identify the cause. Refer to Troubleshooting for possible corrective measures.

Launching the App

Once the app builds successfully, do the following steps to launch the app.

  1. For Mac, you can launch the app from MyApp/build/osx/Debug/MyApp or you can use Xcode as follows:

    1. Navigate to the directory containing the IDE project. Enter:

      cd ~/MyApp/build/osx
      
    2. Start Xcode and open the project. In the Terminal window enter:

      open MyApp.xcodeproj
      

      Xcode opens the project and indexes the project files.

    3. Ensure the MyApp target is selected from the dropdown menu to the right of the Play button.

      Image

    4. Press the Play button in the top-left corner or press Cmd-R to run the app. You may be prompted to enable Developer mode.

      The app displays a blank monochromatic screen while it waits to communicate with a client running on a Roku device.

    5. Prepare the Roku device for local testing as described in Roku Client Builds.

    6. Launch the app installed on the Roku device.

      The app plays simultaneously on a simulator on your development platform and on the test Roku device. Use the Roku controls to interact with the app. Observe the result of your changes.

  2. For Linux, navigate to the build/linux/Debug/bin subdirectory if the build succeeded and run ./MyApp.

Tip You can use the following run time argument for debugging during development:

  • -n1: Use this argument at run time either with XCode or with the app’s executable, as in ./MyApp -n1, to see all the logs and messages on your screen instead of the app’s user interface. You can only see the messages or logs when the app connects to Roku client.
  • -i: Use this argument at run time to launch the app immediately for debugging without the Roku client, as in ./MyApp -i.

Building C++ Roku Apps: Release Version

Production apps are intended to be sent for certification or deployed to the general public. For details, see Deploying Roku Apps. You need to build the Release version of the app for the linux platform target. The procedure is similar to building the Debug version, but requires the extra -c Release argument.

Use the following checklist to ensure you have a correct build environment for the Release version of the app.

  1. The correct versions of CMake and GCC (Linux) are installed installed. See Hardware and Software Specifications.

  2. The following environment variables are configured (see Configuring Roku Environment Variables):
    • YI_CLOUD_SERVER_PORT
    • AWS_ACCESS_KEY_ID
    • AWS_SECRET_ACCESS_KEY
    • YI_SCENEGRAPH_EXPORT_BUCKET
    • YI_SCENEGRAPH_EXPORT_DIR
    • YI_CLOUD_S3_TAG
  3. Confirm your Linux build environment is correctly configured by building a You.i Platform sample app from the You.i Platform package on Linux. See Your first You.i C++ App

  4. Build the Release version of the app. See Release Build Procedure - You.i C++ Roku.

Release Build Procedure: You.i Engine C++ Roku

This procedure assumes you have been successfully building Debug versions of the app as part of your development effort. See Building C++ Roku Apps - Debug Version.

To build your app, run the following command from your project’s youi folder on a Linux computer:

youi-tv build -p osx -d <my_CloudSDK_option>

Substitute <my_CloudSDK_option> for the option you created when you customized your project CMake file. See Step 6 in Additional Developer Setup Tasks and Updating your Legacy C++ App’s Build Files. The following are examples of possible commands depending on your implementation of the CMake file:

  • youi-tv build -p osx -d YI_BUILD_CLOUD_SERVER=ON, or
  • youi-tv build -p osx -d YI_CONFIG_PATH=config/config-osx.txt

Your application is generated in the build/linux/Release/bin subdirectory.

Tip You can use the following run time arguments for debugging during development:

  • -n1: Use this argument at run time either with XCode or with the app’s executable, as in ./MyApp -n1, to see all the logs and messages on your screen instead of the app’s user interface. You can only see the messages or logs when the app connects to Roku client.
  • -m: Use this argument to enable longer node names for debugging in the Release mode.

If the build fails, read and analyze the failure messages to identify the cause. Refer to Troubleshooting for possible corrective measures.