The C++ framework for developing highly scalable, high performance servers on Windows platforms.

• Home
• What
• Why
• How
• Who
• Products
• Pricing
• Blog
• Contact

Search

Configuring the build environment

The Admin Library is where you configure the code to build in the way that you require it to. Every cpp file must include Admin\Admin.h as the first include to ensure that all of the code builds with the same options. Admin\Admin.h itself includes two configuration files that you should edit to specify your preferences, these are Admin\TargetWindowsVersion.h and Admin\Config.h. There are examples of these files in the Admin\ExampleConfigHeaders directory.

TargetWindowsVersion.h

This header file does exactly what you'd expect. It sets the defines required to specify the version of Windows that you are targetting. This enables or disables specific functionality so that you can, for example, build on a Windows Vista machine with the latest Windows SDK and still run on a Windows 2000 machine. If you set these settings incorrectly then you may find that you cannot run on your architecture of choice. The two most important defines that should be set in this file are NTDDI_VERSION and _WIN32_WINNT. See here for more details and (in later Windows SDKs) sdkddkver.h. You may also wish to set JETBYTE_HAS_INTERLOCKED_64 in here, this define determines if we use the Interlocked64 functions if they are available and, again, doing so will restrict the range of operating systems on which you can run.

Config.h

This header is used to set all of the other configuration options for building the source code. Most of the defines that you set in here would previously have been set in Admin\Admin.h they've been moved out so that it's easier for us to build multiple versions of the code on our build servers; a simple file copy changes the desired configuration.

The following defines can be set.

• JETBYTE_ALLOW_UNTESTED_COMPILE_ENV - Define as 1 to suppress the errors for building with a later compile environment than we have tested with. Note that we do not support building with later compile environments but if you want to do so you can.
• JETBYTE_USE_STL_PORT - If you would rather build with STLPort than the standard STL that ships with Visual Studio then you should define JETBYTE_USE_STL_PORT as 1 and you should set the environment variable STLPORT_ROOT to point to, eg, C:\STLport-5.0.0.
• JETBYTE_PLATFORM_SDK_VERSION - Sometimes there are bugs in versions of the Platform SDK (or, perhaps, things we just don't quite understand how to correctly configure...). Rarely we work around these. To be able to work around them we need to know which version of the Platform SDK is being used and the SDK itself cant tell us. So... You can define JETBYTE_PLATFORM_SDK_VERSION with the following values:
  • 0x060A - v6.0a - Vista
  • 0x0610 - v6.1 - Windows Server 2008 and .Net Framework 3.5
  • 0x0700 - v7.0 - Windows 7
  • 0x0800 - v8.0 - Windows 8
  • 0x0810 - v8.1 - Windows 8.1 and .Net Framework 4.5
  At present we only disable the deprecation of the GetVersion functions in the Windows 8.1 SDK by defining BUILD_WINDOWS.
  
  Note that recent versions of the Platform SDK (since it was renamed the Windows SDK) include a file called sdkddkver.h. If you're using one of these SDKs then we can infer the version from the contents of sdkddkver.h, simply include Admin\DetectPlatformSDKVersion.h to do this.
• JETBYTE_SHOW_TODO - Define as 1 to see internal 'todo' messages.
• JETBYTE_HAS_INTERLOCKED_64 - If you're building with _WIN32_WINNT >= 0x0502 and you know that you will be running on a system that supports the Interlocked64() functions then you can define JETBYTE_HAS_INTERLOCKED_64 to 1 and we'll use them in the code. Otherwise we'll cludge around the lack of these 64bit operations with critical sections. Note that you can always compile with _WIN32_WINNT >= 0x0502 and all will be well but if the functions arent exported from Kernel32.dll on the machine that you run on then the process will die at runtime!
• JETBYTE_USE_TEMPLATE_TO_STRING - In version 6.0 we changed how we convert numeric types to strings. Prior to this version we used std::strstream and templates and streamed the type into a string. However this requires the acquisition of a process wide lock (for accessing locales and facets) in some versions of STL which is less than ideal for multi-threaded use. From version 6.0 we default to using a custom sprintf based system to convert from numbers to strings. We also decided to change how 0 is represened in ToHexString(), it's converted to 0x0 in the new code whereas it was converted to 0 in the old. ToHexString() was also enhanced to allow for the user to decide if they want upper or lower case hex digits and we added PointerToString() which gives a consistent represenation of pointers across 32bit and 64bit operating systems (always representing pointers as 64bit hex values). To finish all of these things were moved out of Utils.h and into the ToString.h header file. If you define JETBYTE_USE_TEMPLATE_TO_STRING as 1 then you will revert to the pre version 6.0 behaviour and functionality using std::strstream.
• JETBYTE_WARN_ON_SOCKADDR_STORAGE_DEF - Define as 1 to get warnings when we define our own SOCKADDR_STORAGE structure on versions of Windows < 0x0501.
• JETBYTE_WARN_ON_WSPIAPI_COUNTOF_DEF - Define as 1 to get warnings when we redefine WSPIAPI_COUNTOF with a version that works for earlier compilers.
• JETBYTE_TRANSLATE_SEH_EXCEPTIONS - Define to 1 to have all SEH exceptions tranlated into C++ exceptions (and caught in final catch handlers in all framework threads).
• JETBYTE_TRANSLATE_SEH_EXCEPTIONS_IN_DEBUGGER - Define to 1 to have all SEH exceptions tranlated into C++ exceptions (and caught in final catch handlers in all framework threads) when running in the debugger, if 0 then SEH exceptions are translated only if the debugger is not present when the tranlator is be installed.
• JETBYTE_CATCH_UNHANDLED_EXCEPTIONS - Define to 1 to enable catch(...) handlers. When disabled all catch(...) handlers are removed from library code.
• JETBYTE_CATCH_UNHANDLED_EXCEPTIONS_IN_DESTRUCTORS - Define to 1 to enable catch(...) handlers in destructors. Some destructors have catch(...) handlers present to prevent exceptions leaking from them. This option allows you to remove these handlers. When disabled all catch(...) handlers in destructors are removed from library code.
• JETBYTE_CATCH_UNHANDLED_EXCEPTIONS_AT_THREAD_BOUNDARY - Define to 1 to enable catch(...) handlers in library threads. Most threads that the libraries create have catch(...) handlers present to prevent exceptions leaking from them. This option allows you to remove these handlers. When disabled all catch(...) handlers in threads are removed from library code.
• JETBYTE_CATCH_UNHANDLED_EXCEPTIONS_IN_NOTHROW_FUNCTIONS - Define to 1 to enable catch(...) handlers in 'nothrow' functions in the libraries. Most functions that are marked with a 'no throw' (throw()) exception specification to indicate that the function does not throw exceptions also contain a catch(...) handler to ensure that they don't. This option allows you to remove these handlers. When disabled all catch(...) handlers in 'nothrow' functions are removed from library code.
• JETBYTE_EXCEPTION_STACK_TRACES - Define to 1 to capture the stack strace when an exception derived from JetByteTools::Win32::CException is thrown. Enables the use of JetByteTools::Win32::CException::GetCallStack() to report the callstack at the point of the exception.
• JETBYTE_EXCEPTION_WHERE_INCLUDES_STACK_TRACE - Only valid if JETBYTE_EXCEPTION_STACK_TRACES is defined to 1. Causes JetByteTools::Win32::CException::Where() to also return the call stack of where the exception was thrown.
• JETBYTE_REFERENCE_TRACKING_DISPLAY_LOADED_PDBS - Define to 1 to dump details of the pdb files loaded during the tracking of buffer or socket references.
• JETBYTE_TRACK_IO_BUFFER_REFERENCES - Define to 1 to track where AddRef() and Release() are called from for instances of JetByteTools::IO::CBuffer. If a buffer is over released (i.e. release is called on a buffer where the reference count is currently zero) then a trace of all calls to AddRef() and Release() will be printed to the debug trace output. If a buffer is destroyed and the reference count is not zero then a trace is also printed. Note that there is a considerable run-time cost for this functionality.
• JETBYTE_ADDITIONAL_BUFFER_TRACKING_CONTEXT - By default the buffer reference tracking code keeps one level of call stack context outside of the actual call within the I/O Tools lib code that caused the reference to change. This is often enough context to track down the problem and keeps the amount of memory required for storing call stacks down. Sometimes, however, you need a little more context, in those situations you should define JETBYTE_ADDITIONAL_BUFFER_TRACKING_CONTEXT to a value that represents the additional number of stack frames that you want saved and displayed. Note that each additional level of call stack that is stored requires a DWORD64 of space per call so these additional stack frames can soon add up.
• JETBYTE_TRACK_SOCKET_REFERENCES - Define to 1 to track where AddRef() and Release() are called from for instances of JetByteTools::Socket::TAsyncSocket derived classes. If a socket is over released (i.e. release is called on a socket where the reference count is currently zero) then a trace of all calls to AddRef() and Release() will be printed to the debug trace output. If a socket is destroyed and the reference count is not zero then a trace is also printed. Note that there is a considerable run-time performance cost for this functionality.
• JETBYTE_ADDITIONAL_SOCKET_TRACKING_CONTEXT - By default the socket reference tracking code keeps one level of call stack context outside of the actual call within the Socket Tools lib code that caused the reference to change. This is often enough context to track down the problem and keeps the amount of memory required for storing call stacks down. Sometimes, however, you need a little more context, in those situations you should define JETBYTE_ADDITIONAL_SOCKET_TRACKING_CONTEXT to a value that represents the additional number of stack frames that you want saved and displayed. Note that each additional level of call stack that is stored requires a DWORD64 of space per call so these additional stack frames can soon add up.
• JETBYTE_REFERENCE_COUNTED_SMART_POINTER_THROW_ON_NULL_REFERENCE - Define to 1 to throw exceptions from TReferenceCountedSmartPointer<T>::GetRef() if the reference is null. Normally we simply return the null reference and the calling code goes boom...
• JETBYTE_USE_CAPTURE_STACK_BACK_TRACE - Define to 0 to prevent the use of CaptureStackBackTrace() when building for platforms later than Windows XP. Normally we assume that CaptureStackBackTrace() is available on Windows XP SP1 and later, however if you're building using the default Platform SDK that came with Visual Studio 2005 this does not include CaptureStackBackTrace() and so our platform version check wrongly includes code that cannot build.
• JETBYTE_TINY_XML_2_5_3 - From 6.2 TinyXML version 2.5.3 is available and is used by default. If you would prefer to continue to use TinyXML 2.5.2 then define JETBYTE_TINY_XML_2_5_3 to 0 in your Config.h
• JETBYTE_PERF_STREAM_SOCKETS_SKIP_EVENT_ON_HANDLE, JETBYTE_PERF_DATAGRAM_SOCKETS_SKIP_EVENT_ON_HANDLE, JETBYTE_PERF_FILE_WRITER_SKIP_EVENT_ON_HANDLE
  and JETBYTE_PERF_FILE_READER_SKIP_EVENT_ON_HANDLE
  are all enabled by default. These options enable FILE_SKIP_SET_EVENT_ON_HANDLE on the appropriate handles and potentially provide a small performance improvement. To disable these define the option to 0 in your Config.h
• JETBYTE_PERF_STREAM_SOCKETS_SKIP_COMPLETION_PORT_ON_SUCCESS, JETBYTE_PERF_DATAGRAM_SOCKETS_SKIP_COMPLETION_PORT_ON_SUCCESS, JETBYTE_PERF_FILE_WRITER_SKIP_COMPLETION_PORT_ON_SUCCESS and JETBYTE_PERF_FILE_READER_SKIP_COMPLETION_PORT_ON_SUCCESS. These options enable FILE_SKIP_COMPLETION_PORT_ON_SUCCESS on the appropriate handles and potentially provide a performance improvement in situations where overlapped I/O operations complete straight away as the completion is handled on the thread that initiated the I/O operation rather than being marshalled to an I/O thread. See here for more details.
• JETBYTE_DEBUG_BREAK_ON_CONNECTIONS_ACTIVE_DURING_DESTRUCTION - When enabled a breakpoint is triggered if you are in the debugger and there are connections active when a connection manager is destroyed.
• JETBYTE_DUMP_SOCKET_READ_AND_WRITE_DATA_TO_DEBUG_LOG - When enabled the low level socket I/O code dumps complete details of all data sent and received to the default debug trace log.

---