README.md

   1 Junction is a library of concurrent data structures in C++. It contains three hash map implementations:
   2
   3     junction::ConcurrentMap_Linear
   4     junction::ConcurrentMap_LeapFrog
   5     junction::ConcurrentMap_Grampa
   6
   7 [CMake](https://cmake.org/) and [Turf](https://github.com/preshing/turf) are required. See the blog post [New Concurrent Hash Maps for C++](http://preshing.com/20160201/new-concurrent-hash-maps-for-cpp/) for more information.
   8
   9 ## License
  10
  11 Junction uses the Simplified BSD License. You can use the source code freely in any project, including commercial applications, as long as you give credit by publishing the contents of the `LICENSE` file in your documentation somewhere.
  12
  13 ## Getting Started
  14
  15 If you just want to get the code and look around, start by cloning Junction and Turf into adjacent folders, then run CMake on Junction's `CMakeLists.txt`. You'll want to pass different arguments to `cmake` depending on your platform and IDE.
  16
  17     $ git clone https://github.com/preshing/junction.git
  18     $ git clone https://github.com/preshing/turf.git
  19     $ cd junction
  20     $ mkdir build
  21     $ cd build
  22     $ cmake <additional options> ..
  23
  24 On Unix-like environments, `cmake` will generate a Makefile by default. On Windows, it will create a Visual Studio solution. To use a specific version of Visual Studio:
  25
  26     $ cmake -G "Visual Studio 14 2015" ..
  27
  28 To generate an Xcode project on OS X:
  29
  30     $ cmake -G "Xcode" ..
  31
  32 To generate an Xcode project for iOS:
  33
  34     $ cmake -G "Xcode" -DCMAKE_TOOLCHAIN_FILE=../../turf/cmake/toolchains/iOS.cmake ..
  35
  36 The generated build system will contain separate targets for Junction, Turf, and some sample applications.
  37
  38 ![Solution Explorer](/docs/vs-solution.png)
  39
  40 Alternatively, you can run CMake on a specific sample only:
  41
  42     $ cd junction/samples/MapCorrectnessTests
  43     $ mkdir build
  44     $ cd build
  45     $ cmake <additional options> ..
  46
  47 ## Adding Junction to Your Project
  48
  49 There are several ways to add Junction to your own C++ project.
  50
  51 1. Add Junction as a build target in an existing CMake-based project.
  52 2. Use CMake to build Junction and Turf, then link the static libraries into your own project.
  53 3. Grab only the source files you need from Junction, copy them to your project and hack them until they build correctly.
  54
  55 Some developers will prefer approach #3, but I encourage you to try approach #1 or #2 instead. It will be easier to grab future updates that way. There are plenty of files in Junction (and Turf) that you don't really need, but it won't hurt to keep them on your hard drive either. And if you link Junction statically, the linker will exclude the parts that aren't used.
  56
  57 ### Adding to an Existing CMake Project
  58
  59 If your project is already based on CMake, clone the Junction and Turf source trees somewhere, then call `add_subdirectory` on Junction's root folder from your own CMake script. This will add both Junction and Turf targets to your build system.
  60
  61 For a simple example, see the [junction-sample](https://github.com/preshing/junction-sample) repository.
  62
  63 ### Building the Libraries Separately
  64
  65 Generate Junction's build system using the steps described in the *Getting Started* section, then use it to build the libraries you need. Add these to your own build system. Make sure to generate static libraries to avoid linking parts of the library that aren't needed.
  66
  67 If you build the `install` target provided by Junction's CMake script, the build system will output a clean folder containing only the headers and libs that you need. You can add this to your own project using a single include path. Choose the output directory by specifying the `CMAKE_INSTALL_PREFIX` variable to CMake. Additionally, you can specify `JUNCTION_WITH_SAMPLES=OFF` to avoid building the samples. For example:
  68
  69     $ cmake -DCMAKE_INSTALL_PREFIX=~/junction-install -DJUNCTION_WITH_SAMPLES=OFF ..
  70     $ cmake --build . --target install --config RelWithDebInfo
  71
  72 Notes:
  73
  74 * Instead of running the second `cmake` command, which runs the build system, you could run your build system directly. For example, `make install` on Unix, or build the INSTALL project in Visual Studio.
  75 * If using makefiles, you'll probably want to pass the additional option `-DCMAKE_BUILD_TYPE=RelWithDebInfo` to the first `cmake` command.
  76
  77 This will create the following file structure:
  78
  79 ![Install folder](/docs/install-folder.png)
  80
  81 ## Configuration
  82
  83 When you first run CMake on Junction, Turf will detect the capabilities of your compiler and write the results to a file in the build tree named `include/turf_config.h`. Similarly, Junction will write `include/junction_config.h` to the build tree. You can modify the contents of those files by setting variables when CMake runs. This can be done by passing additional options to `cmake`, or by using an interactive GUI such as `cmake-gui` or `ccmake`.
  84
  85 For example, to configure Turf to use the C++11 standard library, you can set the `TURF_PREFER_CPP11` variable on the command line:
  86
  87     $ cmake -DTURF_PREFER_CPP11=1 ..
  88
  89 Or, using the CMake GUI:
  90
  91 ![CMake GUI](/docs/cmake-gui.png)
  92
  93 Many header files in Turf, and some in Junction, are configurable using preprocessor definitions. For example, `turf/Thread.h` will switch between `turf::Thread` implementations depending on the values of `TURF_IMPL_THREAD_PATH` and `TURF_IMPL_THREAD_TYPE`. If those macros are not defined, they will be set to default values based on information from the environment. You can set them directly by providing your own header file and passing it in the `TURF_USERCONFIG` variable when CMake runs. You can place this file anywhere; CMake will copy it to Turf's build tree right next to `include/turf_config.h`.
  94
  95     $ cmake -DTURF_USERCONFIG=path/to/custom/turf_userconfig.h.in ..
  96
  97 The `JUNCTION_USERCONFIG` variable works in a similar way. As an example, take a look at the Python script `junction/samples/MapScalabilityTests/TestAllMaps.py`. This script invokes `cmake` several times, passing a different `junction_userconfig.h.in` file each time. That's how it builds the same test application using different map implementations.
  98
  99 ## Feedback
 100
 101 If you have any feedback on improving these steps, feel free to [open an issue](https://github.com/preshing/junction/issues) on GitHub, or send a direct message using the [contact form](http://preshing.com/contact/) on my blog.