(C) Zeriph Enterprises
Considerations and Notes
While building, deploying, and working with Omni you might experience certain issues that would initially appear to be a bug with the library code, when it is actually either an erroneous compiler error message or you might not have built and referenced Omni in the same way (as examples). To help with any errors or issues you might run into, we've compiled a quasi Q&A of developer notes and issues to consider when using the library. This list is not a comprehensive list of known issues and does not cover topics that might be in the class documentation, this list is meant more as a developer commentary on issues or other considerations to take note of while using Omni.

If you feel an issue is indeed a bug, please email or contact us to let us know so we can resolve the issue.

Developer Notes

Issue Documentation light/dark theme
Description To change the color theme of the offline documentation, change the first line of the main CSS file (located under 'content/main.css') from `@import url("themes/dark.css");` to `@import url("themes/light.css");` or vice versa to change between a dark and light color theme.
Resolution None; change the theme via the 'main.css' file.
Issue Struct/class padding
Description Considerable effort and care has been put into the classes and structures being properly aligned to byte boundaries to reduce padding, and to ideally have 0 padding. If you compile Omni with other options, like adding the name or disposing members to any class, the padding for that class/struct could be misaligned and thus the compiler will add padding. As well, if you are running on a 32-bit system, you can specify the OMNI_32BIT preprocessor flag to have certain classes compile with 32-bit integer types to reduce or get rid of padding.
Resolution If padding and alignment are of concern, be aware that you can specify the OMNI_32BIT flag for the entire library or individual classes.
Issue Integer types utilized as boolean values
Description Due to the underlying types utilized in a lot of the classes, as they are not simple types that could be represented as bit fields, a lot of the classes utilize an integer type that is bit mapped against constant values, versus utilizing numerous boolean fields. In doing this, the library can be more memory and runtime efficient since the class is memory aligned.
Resolution No resolution is needed, but it should be understood regarding the padding and alignment of the classes. For more information, refer to the issue above regarding struct/class padding.
Issue Virtual thunk error/crash
Description A virtual thunk has to do with how the underlying class pointers are built. A virtual thunk can occur when you build the library as a static or dynamic library to link against (e.g. .lib/.a) with an option such as OMNI_TYPE_INFO, and then build your project, referencing the library and associated headers, without using OMNI_TYPE_INFO. The error occurs because the library source will have the extra members built into it, but the headers referenced in your source will not, thus causing incongruities between your source binary and the library binary.
Resolution Ensure you build your projects with the same build parameters as you supplied to build the library
Issue Static initialization order fiasco
Description Some functionality of the library would fall pray to the initialization of static objects before other static objects were properly initialized, or what is commonly referred to as the Static Initialization Order Fiasco. To this, a few areas of the library follow the Construct on First Use idiom, such as the omni::application class and its member functions for maintaining application state (if used). If you do not call or use these areas of code, then no instances will be created.

Note that if you do call these areas of code and/or run a static memory analyzer, such as Valgrind, it will report those code blocks as "still reachable" after program execution; this is to be expected and should not cause alarm.
Resolution None, just be aware that some areas of code had to be designed a certain way to overcome certain constructs within the C++ language; while some of these limitations are not necessarily an issue in newer versions of the C++ language, Omni does aim to be compatible with C++98 and above, so this must be taken into consideration for older platforms or compilers.
Issue Certain areas of the library may result in truncation of the output based on input type.
Description Many areas of the library utilize templates or return values that could truncate the output of the floating point value. For example, calling omni::math::point_on_circle with a template type that is not a floating point type could give a result that is not precise due to integer conversion and truncation.
Resolution Ensure you understand the precision of the types you are using in templated functions or explicitly define that the function use a floating point type.
Issue Use of any smart_ptr types to any array pointer will not call delete[]
Description The use of any omni::smart_ptr types that are templated to an array pointer will not call delete[]. In other words, if you create an omni::smart_ptr<obj[]>, when the underlying object held by the smart_ptr is no longer needed, it will call the non-array delete on the object and not all objects in the array will be properly freed. Instead you will need to use a smart_ptr<obj*>. If you want a smart pointer type that references a contiguous array type, you will need to use an STL container instead, like a std::vector<obj> or std::deque<obj>; for example: omni::smart_prt<std::vector<obj>>.
Resolution Ensure you do not use improper array types when using a smart pointer type and read the documentation to ensure the limitations and use cases of the Omni library type being used.
Issue External system libraries
Description Some systems might need external system libraries to link properly. For instance, when compiling on certain BSD based systems, -pthread had to be passed to all of the platforms to make use of the threading facilities in the library (via the POSIX thread library), while -rt only had to be passed to some to make use of the real-time system libraries for the timer facilities of the library.
Resolution Ensure you link against the correct system libraries when building.
Issue GLIBC wordexp
Description Some platforms do not implement the GLIBC wordexp (like OpenBSD) for many security reasons. As such, it is not really a good idea to call the omni::environment::expand_vars function without validating the user input; it is there for a convenience function. You can define the OMNI_ENV_WORDEXP compile flag to use wordexp on systems that support it, but it is still generally a good idea to validate user input.
Resolution This is not a bug but could potentially lead to unintended consequences.
Issue Compiler warnings
Description As with any code, it is generally not a good idea to ignore any warnings generated by your compiler. There are some, however, that can be safely ignored once you deduce their true meaning. To this, you might see some warning about old-style casts, or unused references; it is important to note where these warnings are coming from, that is, is the warning coming from the library source itself, or a system header used on a particular platform.

As an example, when compiling on certain systems, you might get a warning about an old-style cast in application.cpp with reference to SIG_ERR. This is because SIG_ERR might be

#define SIG_ERR (void (*)(int))-1

Which is an old-style cast, though not an explicit error to be necessarily concerned with.
Resolution None; compiler warnings should always be investigated.
Issue Compiler warnings continued
Description Enabling certain compiler warnings might yield a warning similar to the following:

'b_val' should be initialized in the member initialization list

However, it is an error to initialize multiple members of a union:

error: initializations for multiple members
Resolution Heed the error and ignore the warning.
Issue Compiler warnings continued again
Description Depending on the level of warnings you enable, for example, -Wcast-function-type or -Wignored-qualifiers, you may notice the library emit a few warning about the generic_ptr, stack_buffer or delegate classes.

For the generic_ptr and stack_buffer classes, the warning is in regards to the const qualifier after a few of the member functions; this const qualifier is there in the event you were to pass one of these classes by const reference to another function; without this const qualifier, an error would be generated instead.

For the delegate classes, the warning is in regards to incompatible function types being casted to/from. This casting is necessary for the delegate classes to work properly.

As such, these warnings can be safely ignored within library itself.
Resolution None; these warnings can be safely ignored.
Issue OMNI_NON_PORTABLE
Description Use of non-portable code can not be portably guaranteed. What that means is that the function used within a block of OMNI_NON_PORTABLE code might not work on all systems, or if it does work you might get varied results from the different platforms.
Resolution None, just be aware of what the OMNI_NON_PORTABLE flag is.
Issue OMNI_NO_WIN_API
Description As detailed in other sections of the help documentation, if the OMNI_WIN_API flag is not enabled, that is, you are electing to use the CRT vs. Windows API calls, some functionality will remain as WinAPI calls.

For instance, there is no CRT equivalent to the WinAPI GetModuleFileName and thus OMNI_NO_WIN_API is not applicable.
Resolution None. This is not a bug but an implementation detail.
Issue OMNI_SEQ_T
Description This #define value is a helper function used throughout the library in place of using a specific C++ sequence container (like the std::vector or the std::deque).

As explained in the help docs, this helper macro is designed to allow a developer the choice of which STL sequence container they might want the library to use. Since it is an STL container, we could not use a simple typedef to define a new type, and we can not use the C++11 using directive (without the OMNI_ENABLE_CXX) to alias the types due to the varying compiler support. To avoid the use/overuse of macros we had considered giving an interface to the defined STL via an overridden class, example: 
namespace omni {
    template <typename T>
    public class seq_t : public virtual OMNI_SEQ_T<T> {};
}
But this presented another set of issues and challenges to be aware of. To this, we have decided to keep this functionality at the macro level for simplicities sake (and because there are not a lot of areas in the code that make use of this feature).
Resolution This is not a bug, but something to be aware of when using the library; considerations are being made for other variations on this issue, should something more clear come along.
Issue OMNI_CHECK_ARITHMETIC_OVERFLOW
Description There are certain classes, like those in the omni::geometry or omni::math namespaces that utilize mathematic operations (e.g. addition, subtraction, etc.). To this, while it is up to the developer to take care not to over/under-flow their operations, if you enable this preprocessor define, then the areas within the library that do have a possibility to overflow or underflow can be checked before the operation and throw an error if there is an over/under-flow condition.

NOTE: Since this check can have a huge impact on performance, this macro is disabled by default and must explicitly be enabled by the user of the library if they wish to have arithmetic overflow checks happen within the library itself.
Resolution None, this option is disabled by default and must be explicitly enabled at compile time to have arithmetic overflow checked within the library; just remember this can impact performance since these checks happen before the specific arithmetic operation occurs. Since this is disabled by default, you must note that certain classes could have their bits overflow (e.g. uint64_t::max + 1 will overflow to 0).
Issue DEV_NOTE
Description Throughout the code you might see a comment with a DEV_NOTE tag to it. These notes are specific to that area of code and are reminders as to why a section of code is the way it is or as a note of platform issues to be aware of.
Resolution None, these are developer notes throughout the source.
Issue .hxx/.cxx files
Description The library has certain files that contain implementation code for certain classes. The code is separated this way for easier reading and debugging but the files are not meant to be included directly in any user code nor are they intended to be compiled directly, otherwise erroneous errors might appear during compilation.
Resolution This is not a bug, but be aware the source files ending in .cxx or .hxx are not meant to be included or compiled directly by any user code.
Issue No header only library
Description The Omni library contains header files and translation units (.cpp files) which must be built in to object files and subsequently assembled into a library file that can be linked against (or compiled into your binary). This is by design, that is, it is a design decision to have Omni not be a header only library for many reasons (name collision, static instances and extern members to name a few).
Resolution Portions of the library are indeed header only, like some of the chrono features, as such these portions of code do not need to be compiled separately as long as there are not extra dependencies on code that does need to be compiled separately.

The library is, however, designed to be compiled via one translation unit. So to build the entire library in one file, you could simply build library.cpp while referencing the source path as an include path, example:

Apple/*nix (using g++): g++ /source/your_code.cpp /source/omni/library.cpp -I/source/omni
Windows (using VS): cl C:\source\your_code.cpp C:\source\omni\library.cpp /IC:\source\omni

That will build your_code.cpp along with the Omni library as one executable binary.
Issue std::swap
Description Certain classes throughout the library allow you to swap 2 objects and their underlying data via that classes swap method. Each of these classes will have a local swap method specific to the class, as well as override std::swap (in the header that defines the class) to call the classes swap method.

Overriding std::swap, while providing a class method swap as well, allows a developer to worry less that the proper swap is called if they simply did swap(t1, t2) or if they indeed chose to explicitly call std::swap(t1, t2) (where t1 and t2 are types from the library).
Resolution None, just be aware that if a class provides a swap method, calling std::swap will call that method.
Issue Standard integer types used through out the library
Description The library will use standard integer types (e.g. int32_t) in any and all places that make sense. However there are a few exceptions, like omni::application::run, that take or return a non-standarized type (like a plain int or long). This is becuase those portions are intended to be utilized with standards compliant functions (like int main(int argc, char* argv[])) or make use of specific platform API's that take non-standardized types for their input (e.g. a WinAPI taking a DWORD).
Resolution None, just be sure to read the documenation and be aware of the few spots in the library that take or return a non-standardized integer type.
Issue Examples are verbose
Description Some examples throughout the documentation might, in some cases, be somewhat verbose in their content. For example, one might see a line like the following:

std::cout << "val[" << x << "]: " << val[x] << std::endl;

and while this line most certainly can be auto'd or put in a macro or function, the point of the examples is to showcase how to utilize certain functionality of the library. To that, making some of the examples less verbose by adding macros or certain functions might actually add more confusion to the example itself and defeat the purpose of said example.
Resolution Read the examples carefully to understand how to utilize a certain function, then adjust the example to fit your needs.
Issue IE compatibility mode
Description If you are viewing this off of your hard drive or intranet, and using Internet Explorer in compatibility mode, the CSS tree views will not work properly.
Resolution Go to 'Tools->Compatibility View Settings' and uncheck 'Display intranet sites in Compatibility View'.
Issue Licensing
Description Omni has a permissive free license that allows you to make derivative works or use Omni how you see fit without worry of license issues.
Resolution None; the license is setup such that those who use the licensed software can do anything with it, except claim it is their work or that Zeriph or its contributors support the new/derived software in any way.