Ubuntu logo

Developer

Scope Development Procedures

Here you can find short procedures for common processes developers need to know about when working with scopes.

Creating a scope

In the Ubuntu SDK, simply create a new project using the Unity Scope template.

File > New File or Project > Unity Scope

scope-wizard-step3-json-net

Tip: During project creation the build kit wizard page displays. Note that when you build the scope, the generated build is placed by default in the parent directory in a directory that starts with ‘build-’ and completes with the project name followed by ‘-Desktop-Default’. For example, if your scope project is named ‘myscope’, your build directory is ../build-my-scope-Desktop-Default.

Tip: For help installing the Ubuntu SDK and creating projects, see Ubuntu SDK Tutorials.

Opening a scope SDK project

Scope projects use CMake for building. CMake projects have a CMakeLists.txt file in the root directory (and in many other project directories).

You can open scope projects from the Ubuntu SDK with the Ctrl + O shortcut and then navigating to and selecting the CMakeLists.txt file in the project’s root directory.

scope-project-open

Opening a scope branch in the SDK as a project

If you have a branch or directory that is a scope source tree that is not an already an SDK project, you can open it and create an SDK project from it, as follows:

  1. Ctrl + O to open a file or project (or use the FileOpen File and Project menu).
  2. Navigate to and select the CMakeLists.txt file in the source tree, then click the Open button.
  3. In the Configure Project dialog that displays, choose the devices kits you want your project to be configured for and click the the Configure Project button.

scope-branch-project-config

From a terminal, you can also navigate to the directory and run

$ ubuntu-sdk .

Building a scope

Tip: When you click the Run button on the left pane of the SDK (or press Ctrl + R), your scope is automatically built before starting.

In the Ubuntu SDK, simply select  Build > Build Project MYSCOPE. (You can also use Ctrl + B) This creates the build directory, which by default is next to the scope project directory and starts with ‘build-’, as described above.

You can also build from the terminal. Move to the build directory (after it is created by building at least once from the SDK) and run: cmake && make

Successful builds generate the following important files in the separate build directory:

  • BUILDDIR/src/llibMYSCOPE.so: the scope’s shared object used by clients that call the scope
  • BUILDDIR/src/llibMYSCOPE.ini: the file used to launch the scope, as discussed next.

Running a scope

If you are using Ubuntu 14.10, you can run a scope on your desktop, directly from the SDK with the Ctrl +R shortcut.

This runs the scope in a standalone window, with developer tools to tweak the ways results are rendered.

unity-scope-tool

  • The scope name or logo displayed in the header is derived from the .ini file
  • The left half of the run window is the scope.
  • The right half is for development purposes. It allows you to modify the scope in various ways. For example, you can click Override category to edit a Category template that controls how results are displayed.

If you are using an earlier version of Ubuntu, you will need to create an emulator from the Devices page of the SDK or connect an Ubuntu phone via USB. There is a tutorial for that.

To run a scope from the terminal, simply use unity-scope-tool followed by the path to your scope .ini file (which is in src/):

$ unity-scope-tool src/myscope.ini

Next step

Now that you are ready to make your first scope, you should give a try to the SoundCloud scope tutorial.