"Improving complex software can be like trying to find a unicorn"
Unikorn Software Event Analyzer
Unikorn is a C API (source code, not a library) and graphical visualizer (Windows, Mac, and Linux) used to easily and quickly improve the design, performance, and reliability of complex software.
Just instrument your source code with meaningful events; you define the names and colors. Run your application, then view the results in UnikornViewer.
Unikorn Presentation
View this presentation to learn the benefits of Unikorn and how to use it
Stable Releases
In the 'Releases' section (right panel of the GitHub webpage, near the top), click on 'Latest' to get the latest stable release, including the pre-built viewer for Mac, Linux, and Windows.
Building
To instrument and build Unikorn into your application, do the following:
Prepare Your Development Environment
| OS | Requirements |
|---|---|
| Linux | gcc make |
| Mac | xCode |
| Windows | Visual Studio Unikorn's API can optionally be thread safe, which requires Posix threads (not supported in Visual Studio). To download and build it: 1. Get the source code from: https://sourceforge.net/projects/pthreads4w/ 2. Unzip, rename to 'pthreads4w' and put in the C:\ folder 3. Start a Visual Studio x64 native shell > cd c:\pthreads4w > nmake VC VC-debug VC-static VC-static-debug install DESTROOT=.\install |
Instrument Your Application with Events
Copy the file examples/hello/unikorn_instrumentation.h into your project to get started. View the
Unikorn Introduction
to see the details on how to instrument your application or just look at the examples/hello/hello.c to get started.
Unikorn's Core Source Files
When using Unikorn in your application, you also need to compile in the following:
- The core Unikorn file
src/unikorn.c # The event recording engine
- One of the Unikorn clock files (or your own custom clock file)
src/unikorn_clock_gettime.c # A clock for Mac/Linux: high precision on most variations
src/unikorn_clock_gettimeofday.c # A clock for Mac/Linux: good precision and portable
src/unikorn_clock_queryperformancecounter.c # A clock for Windows: high precision
src/unikorn_clock_ftime.c # A clock for Windows: not high precision
- Unikorn flushing (or your own custom flush functionality; e.g. socket)
src/unikorn_file_flush.c # Flush event data to a file
The header files for the core, clock, and flush functionality:
inc/unikorn.h
inc/unikorn_clock.h
inc/unikorn_file_flush.h
Examples
To help you get started, some examples are provided
| Example | Description |
|---|---|
| hello | Duh |
| multi_thread_and_file | Shows how multi-threaded processing can effect memory accesses. Also shows how multiple event files can be time aligned. |
| test_clock | Helpful if you need to characterize the overhead and precision of a clock. |
| test_record_and_load | A simple and full featured (including folders) example used to validate the unikorn API and event loading using src/unikorn_file_loader.c |
Visualizer
UnikornViewer is written in C++ using the Open Source Qt framework (www.qt.io).
Get the pre-built viewers from the 'Releases' section (right panel of the GitHub webpage, near the top), click on 'Latest' to get the latest release.
To manualy build it yourself, do the following:
Tested with Qt Qt 5.15.2
Linux and Mac
> cd unikorn/visualizer
> qmake
> make -j8
> ./UnikornViewer
Windows
> cd unikorn\visualizer
> qmake
> nmake
> release\UnikornViewer.exe
Optionally Develop a Visualizer or Application to Analyze the Events
If you are creating you own graphical visualizer, or just need to load events into some post-processing application, you can use the supplied source code to load the events:
src/unikorn_file_loader.c # Code for load a .events file
int/unikorn_file_loader.h # Header file for unikorn_file_loader.c