Getting Started
Installation
To build ginger, you will need to have CMake. For most
you can use your package manager, e.g. apt-get
, pacman
or yum
on Linux
or homebrew
, macports
or fink
on OS X.
Linux, OS X, and Windows (Bash, MinGW and Cygwin)
Once CMake is installed, building, testing and installing the library is a snap
λ cmake . -DCMAKE_BUILD_TYPE=Release -DEXAMPLES=Yes
λ make all tests
λ sudo make install
Windows with MSVC
Building with MSVC is a bit more involved. Open the Visual C++ MSBuild command prompt (should be in your start menu). You can then run cmake build and test from the prompt:
λ cmake -DCMAKE_BUILD_TYPE=Release -G"Visual Studio 14 2015" -DEXAMPLES=Yes
λ msbuild /p:Configuration=Release ALL_BUILD.vcxproj
λ test\Release\ginger_unittest.exe
Installation requires the user to manually copy the headers and libraries to wherever the user would like.
Getting Help
Ginger is developed to help you write better C code faster, but I can’t do it without your feedback. I host the project’s source code and issue tracker on GitHub. Please create an issue if you find a bug, an error in this documentation, or have a feature you’d like to request.
- Ginger Source Repository
- Issue tracker
Copyright and Licensing
Copyright © 2016-2017 Douglas G. Moore. Free use of this software is granted under the terms of the MIT License.
See the LICENSE file for details.
Dynamics Arrays
Ginger provides a "fat pointer" implementation of dynamic arrays called
gvector
. This means that ginger’s dynamic arrays look and feel like C-style
arrays, but have additional structural informational such as their capacity,
length and element size.
Type Definitions | |
Accessors | |
Memory Management |
gvector_alloc, gvector_free, gvector_dup, gvector_copy, gvector_reserve, gvector_shrink |
Stack Operations |
Type Definitions
Memory Management
Stack Operations
Unit Testing Framework
Ginger provides a simple unit testing framework, called unit
. Unit lets the
user create unit tests, test suites, and simplifies creating a single unit
testing executable. In this section we’ll walk through the recommended file
structure for using unit
. Ginger uses unit
for its own unit testing, so
a working example can be found in
test.
Examples
A Single Test Suite
We start by creating and registering a canary test suite, and setting up a basic entry point for our test executable.
#include <ginger/unit.h>
UNIT(CanaryTest) {
ASSERT_EQUAL(5, 1 + 2); // Should fail
}
BEGIN_SUITE(CanarySuite)
ADD_UNIT(CanaryTest)
END_SUITE
BEGIN_REGISTRATION
REGISTER(CanarySuite)
END_REGISTRATION
UNIT_MAIN()
We can then compile and run our unit tests
λ gcc -std=c11 -o unittest main.c
λ ./unittest
[SUITE] CanarySuite
[TEST] CanaryTest main.c:4 - expected 5, got 3 [FAIL]
RESULTS: 1 tests (0 ok, 1 failed)
Since unit
is a header-only utility, there is no need to link against the
ginger
library. However, you will need to make sure the ginger/unit.h
header
is in your include path.
Additional Test Suites
Now, let’s add another suite, Vector
, to test ginger’s dynamic array type
gvector.
#include <ginger/vector.h>
#include <ginger/unit.h>
UNIT(VectorAlloc) {
int *xs = gvector_alloc(5, 3, sizeof(int));
ASSERT_NOT_NULL(xs);
ASSERT_EQUAL_U(5, gvector_cap(xs));
ASSERT_EQUAL_U(3, gvector_len(xs));
ASSERT_EQUAL_U(sizeof(int), gvector_size(xs));
gvector_free(xs);
}
BEGIN_SUITE(Vector)
ADD_UNIT(VectorAlloc)
END_SUITE
Once we’ve created the new suite, we need to register it. We use the IMPORT_SUITE macro to import the suite, and modify the registration section of main.c.
IMPORT_SUITE(Vector);
BEGIN_REGISTRATION
REGISTER(CanarySuite)
REGISTER(Vector)
END_REGISTRATION
We can now compile and run the unit tests. Note that we are now linking against
libginger
because we’re using ginger’s vector functionality.
λ gcc -std=c11 -o unittest main.c vector.c -lginger
λ ./unittest
[SUITE] CanarySuite
[TEST] CanaryTest main.c:4 - expected 5, got 3 [FAIL]
[SUITE] Vector
[TEST] VectorAlloc [OK]
RESULTS: 2 tests (1 ok, 1 failed)
- Test Suite
- Entry Point
-
IMPORT_SUITE, BEGIN_REGISTRATION, REGISTER, END_REGISTRATION, UNIT_MAIN
- Assertions
-
ASSERT_TRUE, ASSERT_FALSE, ASSERT_EQUAL, ASSERT_NOT_EQUAL, ASSERT_EQUAL_U, ASSERT_EQUAL_P, ASSERT_NULL, ASSERT_NOT_NULL, ASSERT_NAN, ASSERT_NOT_NAN, ASSERT_INF, ASSERT_NOT_INF, ASSERT_DBL_NEAR, ASSERT_DBL_NEAR_TOL, ASSERT_DBL_ARRAY_NEAR, ASSERT_DBL_ARRAY_NEAR_TOL, ASSERT_SIGNAL