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.
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:
doc: this is the directory that contains Sparksee API reference documentation in html or the specific format for the different platforms.lib: a directory with Sparksee libraries. This may have subdirectories when different files are required regarding each operating system.ReleaseNotes.txt: a text file with basic information on the latest release changes. release changes.LICENSE.txt: contains Sparksee licensing information.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.
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:
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> 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.
Copy the sparkseejava.jar file from the lib/ directory to the libs/ directory of your android project.
If you want different “.apk” files for the different target architectures instead of a single application file that supports all platforms or you only want to support certain architectures, you just need to remove from inside the sparkseejava.jar the subdirectories of the platforms that you don’t want.
Refresh the project explorer if you can’t see the copied files.
Right click on the libs/sparkseejava.jar file and select Add as library....
Verify that in your build.gradle you have a command to compile the jar file. Probably there will be the command compile fileTree(dir: 'libs', include: ['*.jar']) If it’s not present you could add this command compile files('libs/sparkseejava.jar') to compile at least the sparkseejava.jar file.
Set a minimum sdk version >= 9 in the build.gradle file.
Right click on the libs/sparkseejava.jar file and select Build Path > Add to Build Path.
Set in your AndroidManifest.xml a minimum sdk version greater or equal to 9.
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.
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.
Since all the other libraries included in the package are native libraries that will be loaded at runtime, they must be available too.
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).
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.
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.
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.
or with the vcvarsall.bat file with the appropiate argument for 64 bit MS Visual Studio.
Then the application can be compiled and run (assuming all the libraries have already been copied to the same directory) as follows:
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.
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.
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.
After this, the sparksee library should be added to the Additional Dependencies linker input property.
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.
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.
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.
or with the vcvarsall.bat file with the appropiate argument for the 64-bit MS Visual Studio.
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.exeWe 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.
In the includes directory, there is the subdirectory sparksee that must be added as included search directories in the project.
The lib directory contains a subdirectory for each available operating system. The correct directory for the computer should be added as a link search directory in the project.
To link the application, the sparksee, and the pthread libraries must be used in this order.
Finally the directory where the libraries can be found may be added to the LD_LIBRARY_PATH, or DYLD_LIBRARY_PATH in MacOS, environment variable to ensure that they will be found at runtime.
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/
$ ./HelloSparkseeThe Android is not very different from the Linux usage.
You also must add the includes/sparksee directory to the includes search path.
The sparksee dynamic library and the provided stlport_shared library must be included in the applicacion. There are 4 versions of each library in subdirectories from the lib/ directory. You must use the appropiate libraries for the processor target of your project.
The stlport_shared is the NDK library must be included in the application instead of just being linked.
The z and dl libraries from the Android NDK must be linked too.
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.
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:
Add the Sparksee include files to the search path in your application project: The path to Sparksee.framework/Resources/sparksee/ must be added as non-recursive to the User Header Search Paths option on the build settings of your xcode application project. This is required because Sparksee include files use a hierarchy of directories which is not usual in an xcode framework. Therefore, they can’t be in the regular headers’ directory of the framework.
Add the Sparksee.framework to the Link Binary With Libraries build phase of your application project. You can just drag it there.
Choose the appropiate 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. The option choosen must match the downloaded version of the Sparkseecpp for iOS.
Remember that all the source files using C++ should have the extension “.mm” instead of “.m”.
Take into account that, after all these changes, a Clean of your Project may be needed.
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.
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:
DYLD_LIBRARY_PATH for MacoOSX systems.
LD_LIBRARY_PATH for Linux systems.
PATH environment variable for Windows systems.
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.
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.
MacOS
The dmg file for Mac OS contains an installer (SparkseeInstaller.pkg) to run. This will extract the framework directory to the right location (/Library/Frameworks/Sparksee.framework).
If you are asked for a target disk, you must choose the main system disk. Your application will depend on the Sparksee dynamic library, so it will need to find it in the right location at runtime.
iOS
The dmg file for iOS contains the Sparksee.framework directory without an installer because you can copy it to any place.
When building your application the Sparksee library will be embedded. Sice it’s not a dynamic library framework, it doesn’t need to be found at any specific location at runtime.
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.
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 <Sparksee/Sparksee.h> header in your source code.
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.
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 <Sparksee/Sparksee.h> header in your source code.
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.