Installation

System requirements

Sparksee is available for several platforms:

Furthermore, Sparksee is available for several programming languages:

Sparksee has a small footprint and it does not have any specific requirements for the memory size or disk capacity of the platform. Thus, these aspects will solely depend on the user's data size and application.

Download

Sparksee is available for several programming languages, so the first thing to do is download the right package for a development platform and language. All the packages can be downloaded in the download section of the Sparsity technologies website.

Java developers can also get Sparksee through Apache Maven instead of manually downloading the packages. More information is available in Sparksee maven project.

Available packages:

Once Sparksee is downloaded and unpacked, the content of most packages should look like this:

According to the programming language particularities, some packages may include additional content.

Sparksee package is now ready to be used. No further installation is required, with the exception of Objective-C on MacOS, where an installer is provided to easily copy the framework to the right standard directory.

However, some additional steps can be taken to make Sparksee usage easier for every language.

We will use the HelloSparksee application for the examples which is available for download here.

Java

All the libraries required to develop a java application with Sparksee are contained in a jar file located at the lib directory (sparkseejava.jar).

In Windows, the core of Sparksee are native C++ libraries that require the appropiate Microsoft Visual C Runtime installed. The current java version requires the MSVC 2012 runtime.

If the user is not using Maven, a path to this file should be added into the CLASSPATH environment variable. However, to avoid any misunderstandings, in this document we will explicitly set the classpath for each of the commands. The HelloSparksee application can be compiled and run as follows:

$ javac -cp sparkseejava.jar HelloSparksee.java
$ java -cp sparkseejava.jar;. HelloSparksee 

With Maven

With Apache Maven it is even easier. Since Sparksee is in the maven central repository, adding the dependency to the correct Sparksee version into a pom.xml file should be enough:

<dependency>
  <groupId>com.sparsity</groupId>
  <artifactId>sparkseejava</artifactId>
  <version>5.0.0</version>
</dependency> 

With Android

The procedure to use Sparkseejava in Android is the same for Eclipse and Android Studio, but we have separated some steps to better explain the procedure in each environment.

Android Studio

Using Eclipse

.NET

The .NET package contains subdirectories in the lib directory for each platform and compiler (windows32_VS2012, windows64_VS2012, ...). You should chose the right one for 32 or 64 bit systems and your complier. For each system, the main library included is sparkseenet.dll which should be included in the .NET projects.

All the other available libraries in the package are native dlls that sparkseenet.dll must be able to find at run time. Although it is not a requirement, these libraries may be copied to the system folder.

The core of Sparksee are native C++ libraries that require the appropiate Microsoft Visual C Runtime installed on all the computers running your application.

MS Visual Studio users

If you are a MS Visual Studio IDE developer, you need to add the reference to the Sparksee .NET library (sparkseenet.dll) in your project and set the build platform to the appropiate specific platfrom (x64 or x86). Please, check that in the "Configuration Manager" from the "BUILD" menu of Visual Studio, the "Platform" selected for the build is NOT "Any CPU". If it's "Any CPU", you must select "New" to set a "x86" or "x64" build target.

Figure 3.1: .Net compilation - setting the platform

Figure 3.1: .Net compilation - setting the platform

Since all the other libraries included in the package are native libraries that will be loaded at runtime, they must be available too.

Figure 3.2: .Net compilation - adding the reference

Figure 3.2: .Net compilation - adding the reference

The best option is to copy all the other ".dll" files into the same directory where your application executable file will be.

Using the development environment, this can be done using the option Add existing Item, choosing to see Executable files and selecting the other three native libraries (sparksee.dll, sparkseenetwarp.dll and stlport.dll).

Figure 3.3: .Net compilation - adding existing item

Figure 3.3: .Net compilation - adding existing item

Next you must select the three libraries in the Solution Explorer window and set the property Copy to Output as Copy Always for all three native libraries.

Figure 3.4: .Net compilation - copy to output

Figure 3.4: .Net compilation - copy to output

Instead of copying the native libraries to the application target directory, an alternative would be to put all the native ".dll" files into your Windows system folder (System32 or SysWOW64 depending on your Windows version).

Now the application is ready to be built and run like any Visual Studio project.

Command-line users

Alternatively the command-line interface might be used as well to test the sample application.

First setup a compiler environment with the vsvars32.bat (or vcvarsall.bat) for 32 bit MS Visual Studio.

> call "C:\Program Files\Microsoft Visual Studio 11.0\Common7\Tools\vsvars32.bat"

or with the vcvarsall.bat file with the appropiate argument for 64 bit MS Visual Studio.

> call "C:\Program Files (x86)\Microsoft Visual Studio 11.0\VC\vcvarsall.bat" amd64

Then the application can be compiled and run (assuming all the libraries have already been copied to the same directory) as follows:

> csc /out:HelloSparksee.exe /r:sparkseenet.dll HelloSparksee.cs
> HelloSparksee.exe

C++

The C++ lib folder contains native libraries for each available platform (Windows 32/64 bit, Linux 32/64 bit and MacOS 64 bit, ...).

In Linux and MacOS, you may want to add the path to the correct subdirectory to your LD_LIBRARY_PATH (linux) or DYLD_LIBRARY_PATH(MacOS) environment variables.

In Windows the libraries can either be copied to the system folders or the user must take care to always include them in the projects.

The rest of the files included in this package, such as the ones in the includes directory, will be needed at compilation time.

For iOS you have to uncompress the ".dmg" file to get the Sparksee.framework directory. This directory contains the include files, the static library and the documentation. But you may prefer to use the Objective-C version of Sparksee.

The Sparksee C++ interface contains include files and dynamic libraries in order to compile and run an application using Sparksee. The general procedure is to first add the include directories to your project, then link with the supplied libraries corresponding to your operating system and finally copy them to any place where they can be loaded at runtime (common places are the same folder as the target executable file or your system libraries folder).

Let's have a look at a more detailed description of this procedure in the most common environments.

Windows users

When using the development environment Microsoft Visual Studio, the first step should be to add to the Additional include directories, C++ general property of the project, the sparksee subdirectory of the includes folder from the Sparksee package.

Figure 3.5: C++ compilation - include directories

Figure 3.5: C++ compilation - include directories

This must also be done with the library directory, so the Additional library directories linker general property must be edited to add the correct subdirectory of the Sparksee lib folder for the operating system and compiler used.

Figure 3.6: C++ compilation - add library directories

Figure 3.6: C++ compilation - add library directories

After this, the sparksee library should be added to the Additional Dependencies linker input property.

Figure 3.7: C++ compilation - add dependencies

Figure 3.7: C++ compilation - add dependencies

Finally ensure that the dll files can be found at run time. An easy way to do this is to add a post-process in the project to copy the dll files to the output folder where the application executable will be built.

Figure 3.8: C++ compilation - post build event

Figure 3.8: C++ compilation - post build event

An alternative would simply be to put all the native *.dll files into the Windows system folder (System32 or SysWOW64 depending on the Windows version).

It's important to check that the build platform selected matches the libraries that you are using.

Figure 3.9: C++ compilation - platform

Figure 3.9: C++ compilation - platform

Now it is ready to build and run the application like any MS Visual Studio project.

Optionally, to quickly test the HelloSparksee sample application, the command line can be used instead of the MS Visual Studio approach. First, set up the compiler environment with the vsvars32.bat (or vcvarsall.bat) file with the 32-bit MS Visual Studio.

> call "C:\Program Files\Microsoft Visual Studio 11.0\Common7\Tools\vsvars32.bat"

or with the vcvarsall.bat file with the appropiate argument for the 64-bit MS Visual Studio.

> call "C:\Program Files (x86)\Microsoft Visual Studio 11.0\VC\vcvarsall.bat" amd64

Then to compile and run the application (example on a 32-bit Windows):

> cl /I"path_to_the_unpacked_sparksee\includes\sparksee" /D "WIN32" /D "_UNICODE" /D "UNICODE" /EHsc /MD /c HelloSparksee.cpp

> link /OUT:"HelloSparksee.exe" HelloSparksee.obj /LIBPATH:"path_to_the_unpacked_sparksee\lib\windows32" "sparksee.lib"

> xcopy /y "path_to_the_unpacked_sparksee\lib\windows32\*.dll" .

> HelloSparksee.exe

Linux/MacOS users

We are not going to focus on any specific integrated development environment for Linux or Mac OS as that is beyond the scope of this manual. Instead we will give an explanation of the procedure which can be adapted to the specifics of any development environment.

Optionally, to quickly test the HelloSparksee sample application, the command line can be used as well:

$ g++ -I/path_to_the_unpacked_sparksee/includes/sparksee -o HelloSparksee.o -c HelloSparksee.cpp 

$ g++ HelloSparksee.o -o HelloSparksee -L/path_to_the_unpacked_sparksee/lib/linux64 -lsparksee -lpthread

$ export LD_LIBRARY_PATH=/path_to_the_unpacked_sparksee/lib/linux64/

$ ./HelloSparksee

Android

The Android is not very different from the Linux usage.

iOS

Once you have extracted the Sparksee.framework directory from the distribution ".dmg" file, the basic steps to use Sparksee in your Xcode application project are the following:

Python

Python lib contains the native libraries for each available platform (Windows 32/64 bits, Linux 32/64 bits and MacOS 64 bits) in addition to the Python module.

Make sure to include both the Python module (called sparksee.py) and the wrapper library named "_sparksee" in an accessible folder for Python, please refer to Python module search path for more information about the search path.

The other available library included in Sparksee's Python distribution is the dynamic native library. This must be located in a specific system directory defined by the following:

Once the installation is completed you can run the script normally. The following example assumes that the python2.7 executable is available in your path, otherwise you should write the full path to your Python executable.

$ python ./HelloSparksee.py

Objective-C

For the Objective-C Mac OS and iOS versions, the content of the dmg file is slightly different because, you will either find the Sparksee.framework directory or its installer. The documentation is in the framwork subdirectory Resources/Documentation.

The MacOS and iOS versions can be included in you application project in the same way and could be used equally from the source code. But the installation of the framework and deployment of your application is slightly different.

MacOS

We have seen how to download, unpack the dmg file and install the Sparksee package to get the Sparksee.framework installed in the /Library/Frameworks/ directory. The Mac OS version of the framework is a standard framework containing a dynamic library, so it's installed in a fixed standard location.

To use the Sparksee Objective-C framework in your application, you have to add the Sparksee.framework from /Library/Frameworks/Sparksee.framework to the Link Binary With Libraries build phase of your application project.

Then you can import the header in your source code.

#import <Sparksee/Sparksee.h>

Take into account that your application will depend on the Sparksee dynamic library, therefore the Sparksee framework must be installed on the target computers either manually or redistributed with your own installer.

Alternatively, you could include the framework as a private framework inside your application, but then a modification of the framework library location on the @executable_path instead of the standard /Library/Frameworks/ would be required.

iOS

We have already seen how to download and unpack the dmg file. For iOS, you don't need to install the framework because it would be already there. You can copy it directly to wherever you want because there is not any established standard dynamic library framework.

To use the Sparksee Objective-C framework in your application, you have to add the Sparksee.framework to the Link Binary With Libraries build phase of your application project. You can just drag it there.

If you don't use C++ code in your project, you have to explicitly add the right C++ standard library because the Sparksee library core depends on it. Click on the "+" sign of the same "Link Binary With Libraries" build phase of your application project, then select the appropiate C++ library ("libc++.dylib" for LLVM C++11 version or "libstdc++.6.dylib" for the GNU C++ version) and finally click the "Add" button.

If you use C++ in your code, choose the right library ("libstdc++ (GNU C++ standard library)" or "libc++ (LLVM C++ standard library with C++11 support)") in the "C++ Standard Library" option in the build settings of the compiler depending on the Sparksee version downloaded.

Then you can import the header in your source code.

#import <Sparksee/Sparksee.h>

Your iOS application will contain the Sparksee library embedded (it's a static library), so your application deployment should be exactly the same as any other iOS application.

Setting an explicit memory limit to the Sparksee cache (using the SparkseeConfig class) is highly recommended. For more information about SPARKSEE cache and the SPARKSEEConfig class check the Configuration chapter and the reference guides.

Back to Index