nlib
|
This manual is a collection of libraries that support Windows, Linux, FreeBSD, OS X, Cygwin, and Nintendo's development environments.
nlib
is being developed to provide a group of user-space libraries that enable you to program for Windows, Linux, FreeBSD OS X, Cygwin, and Nintendo's development environments using the same interface. Its development follows a software-centric approach, adopts appropriate and pragmatic coding rules (nlib Coding Rules
), and implements an interface that is independent from the individual development environments. This focus makes it possible to develop in parallel for multiple development environments while maintaining high quality, performance, and reliability.Platform | Library types | Remarks | ||
---|---|---|---|---|
Windows | Visual Studio 2017 | 64bit | static library, DLL | Version 15.3 |
Visual Studio 2015 | 64bit | static library, DLL | Update 3 | |
32bit | static library | |||
Visual Studio 2013 | 64bit | static library, DLL | Update 5, Express Edition is available | |
32bit | static library | |||
Cygwin | 64bit | static library | gcc 6.4.0, newlib, libstdc++ | |
Bash on Ubuntu on Windows | 64bit | shared library | Ubuntu 16.04 | |
Linux | Ubuntu 17.04 | 64bit | shared library | gcc 6.3.0, clang 4.0.0, glibc, libstdc++, https://app.vagrantup.com/bento/ |
Ubuntu 16.04 LTS | 64bit | gcc 5.3.1, clang 3.8, glibc, libstdc++, https://app.vagrantup.com/bento/ | ||
Ubuntu 14.04 LTS | 64bit | gcc 4.8.4, clang 3.4, glibc, libstdc++, https://app.vagrantup.com/ubuntu/ | ||
32bit | ||||
CentOS 7 (v1708.01) | 64bit | devtoolset-4, gcc 5.3.1, libstdc++, https://app.vagrantup.com/centos/ | ||
Fedora 26 | 64bit | gcc 6.2.1, clang 3.8, glibc, libstdc++. https://app.vagrantup.com/fedora/ | ||
Alpine 3.6.0 | 64bit | gcc 6.3.0, musl libc, libstdc++, https://app.vagrantup.com/maier | ||
FreeBSD | FreeBSD 11.1 | 64bit | shared library | clang 4.0, BSD libc, libc++, https://app.vagrantup.com/freebsd/ |
macOS | macOS 10.13 (High Sierra) | 64bit | shared library | Xcode 9.0 |
CTR | CTR-SDK 11.5 | 32bit | static library | CTR_SDK-11_5_2-20161105-ja.zip armcc_4_1_nintendo-b1454-20150227.zip |
Cafe | CafeSDK 2.13.01 | 32bit | static library | cafe_sdk-2_13_01-20150728.zip MULTI-5_3_26-20150918.zip |
nlib
. It is a good idea to use the testing
library to create these types of acceptance tests. nn::nlib::testing
format and include it in your bug report.├── bin │ └── cmake # Command-line tools ├── cmake # Common Cmake scripts ├── documents-en │ └── API # Reference Manual │ ├── html # HTML version of the Reference Manual │ └── searchdata.xml # Search index ├── include # Include files (in `system/include` for Cafe) │ ├── nn │ │ └── nlib │ │ ├── exi │ │ ├── heap │ │ ├── msgpack │ │ │ └── jsonrpc │ │ ├── oss │ │ ├── simd │ │ ├── succinct │ │ ├── testing │ │ ├── threading │ │ └── unicode │ ├── lz4.h │ ├── lz4hc.h │ ├── lz4frame.h │ ├── sqlite3.h │ └── sqlite3ext.h ├── lib # Platform-specific library files (`system/lib` for Cafe, `libraries` for CTR) ├── samples # Source code for samples │ ├── cmake │ └── sources │ ├── exi │ ├── heap │ ├── misc │ ├── msgpack │ ├── oss │ ├── succinct │ └── testing └── setup ├── setup-bash-ubuntu-windows-tools.sh ├── setup-cygwin-tools.sh ├── setup-msvc-libraries.ps1 └── setup-osx-tools.sh
nlib_epochtime()
, that obtain the current time. nlib_gen_random()
function that obtains random values. nlib_mutex
) nlib_cond
) nlib_tls
) nlib_barrier
) nlib_once()
) nlib_rwlock
) nlib_condrwlock
) nlib_mq
) nlib_atomic_compare_exchange32()
, that atomically rewrite memory. nlib_debug_break()
and nlib_debug_backtrace()
, that access the debugger. nlib_getenv()
function that obtains environment variable values. nlib_fd_open()
. nlib_strto_int32()
, that wrap standard C functions, including strtol()
and strtoll()
, in a way they are not wrongly used. nlib_isspace()
, that implement standard C functions defined by ctype.h
in a way they are not affected by the locale. nlib_snprintf()
, that are adjusted to suppress differences among the environment-specific behaviors of snprintf()
, snwprintf()
, and other similar functions to prevent them from being wrongly used. nlib_swapendian_32()
) nlib_crc32()
and nlib_crc32c()
) nlib_popcnt64()
) InputStream
and OutputStream
MemoryInputStream
and MemoryOutputStream
) FileInputStream
and FileOutputStream
) Base64InputStream
and Base64OutputStream
) zlib
-compressed data (ZlibInputStream
and ZlibOutputStream
) TextReader
and TextWriter
) BinaryReader
and BinaryWriter
) unicode::UnicodeNormalizer
) unicode::StringPrep
) libn
library. std::thread
that runs without C++03 or C++ exceptions (threading::Thread
) std::future
and std::async
that run without C++03 or C++ exceptions (threading::Future
and threading::Async
) threading::ThreadPool
) Uri
) UriTemplate
) NativePathMapper
). threading::AsyncFileIo
) LockFreeInit()
, for initializing lock-free objects. LockFreePipe
) that can be used when one sender thread is associated with only one receiver thread. LockFreeStack
) LockFreeQueue
) LockFreePriorityQueue
) LockFreeBroadcastQueue
) std::unique_ptr
(UniquePtr
). In C++11, this class is defined as std::unique_ptr
using a typedef
. Singleton
and SimpleSingleton
) std::vector
-like class that does not require freeing memory and copying elements upon expansion (Nlist
) Nflags
) HandleMaker
) nn::nlib
, nn::nlib::unicode
, and nn::nlib::threading
.nn::nlib::exi
.nmalloc
and nfree
functions (and the heap::CachedHeap
and heap::CentralHeap
classes used to implement them) keep performance degradation in check by controlling fragmentation through the use of multi-level free lists. By maintaining per-thread caches for small blocks of memory, memory can be allocated and freed without locking, which helps to limit the degradation of multithreaded performance. Pointers within the free lists are checked for both mangling and their allocation status. This implementation makes it more difficult to use them in an invalid way by overwriting memory externally. nn::nlib::heap
and the global namespace (C linkage functions).succinct
library includes the following. nn::nlib::succinct
.msgpack
library includes the following. nn::nlib::msgpack
.nn::nlib::testing
. (It is aliased to the testing
namespace for the sake of Google Test compatibility.) It depends on the misc
library.zlib
instead of bzlib2
, and the corresponding command-line programs nlib
, and a corresponding command-line shell zlib
, and approximately five times faster at decompression. nn::nlib::oss
and the global namespace (C linkage functions).simd
library makes it possible to write code that supports both SSE4.2 and NEON. nn::nlib::simd
.The dependency between nlib
libraries is as shown in the following figure.
nlib
is compiled using C++11/14/17 features for some combinations of compilers and versions. Whether the compiler supports those features is determined based on the compiler version and using Feature Testing Macros recommended in C++14 and later. C++11 Feature | Identification Macro | Macros and Typedefs for C++03 Compatibility | Visual Studio | gcc |
---|---|---|---|---|
Rvalue references | __cpp_rvalue_references | None | 2010 | 4.3 |
Variadic templates | __cpp_variadic_templates | None | 2013 | 4.7 |
Static assertions | __cpp_static_assert | NLIB_STATIC_ASSERT() | 2010 | 4.3 |
Null pointer constant | NLIB_CXX11_NULL_POINTER_CONSTANT | nn::nlib::nullptr, nn::nlib::nullptr_t | 2010 | 4.6 |
Deleted functions | NLIB_CXX11_DEFAULTED_AND_DELETED_FUNCTIONS | NLIB_DISALLOW_COPY_AND_ASSIGN() | 2015 | 4.4 |
Explicit conversion operators | NLIB_CXX11_EXPLICIT_CONVERSION_OPERATORS | NLIB_SAFE_BOOL() | 2013 | 4.6 |
Alias templates | __cpp_alias_templates | None | 2013 | 4.7 |
constexpr | __cpp_constexpr | NLIB_CEXPR | 2015 | 4.7 |
char16_t, char32_t | __cpp_unicode_characters | nlib_utf16_t, nlib_utf32_t | 2015 | 4.4 |
alignas | NLIB_CXX11_ALIGNMENT_SUPPORT | NLIB_ALIGNAS() | 2015 | 4.8 |
Explicit virtual overrides | NLIB_CXX11_EXPLICIT_VIRTUAL_OVERRIDES | NLIB_OVERRIDE | 2012 | 4.7 |
final | NLIB_CXX11_EXPLICIT_VIRTUAL_OVERRIDES | NLIB_FINAL | 2012 | 4.7 |
noexcept | NLIB_CXX11_NOEXCEPT | NLIB_NOEXCEPT | 2015 | 4.6 |
Range-based for | __cpp_range_based_for | None | 2012 | 4.6 |
lambda | __cpp_lambdas | None | 2012 | 4.7 |
Delegating constructors | __cpp_delegating_constructors | None | 2013 | 4.7 |
std::unique_ptr | NLIB_CXX11_UNIQUEPTR | nn::nlib::UniquePtr | 2013 | 4.7 |
#include <random> | NLIB_CXX11_STDLIB_RANDOM | None | 2013 | 4.8 |
#include <chrono> | NLIB_CXX11_STDLIB_CHRONO | Conversion to and from nn::nlib::DateTime | 2012 | 4.7 |
#include <atomic> | NLIB_CXX11_STDLIB_ATOMIC | NLIB_MEMORY_ORDER_SEQ_CST and others | 2012 | 4.8 |
#include <array> | NLIB_CXX11_STDLIB_ARRAY | None | 2012 | 4.5 |
#include <unordered_map> #include <unordered_set> | NLIB_CXX11_STDLIB_UNORDERED | None | 2012 | 4.5 |
#include <tuple> | NLIB_CXX11_STDLIB_TUPLE | None | 2012 | 4.5 |
nlib
coding rules are a slight modification and relaxation of the latest version of the Google C++ Style Guide (and a slightly outdated Japanese translation). nlib
are shown below. Coding rule | Google C++ Style Guide | nlib |
---|---|---|
Line length | 80 | 100 |
Indentation | 2 | 4 |
Parameter order | Inputs followed by outputs | Outputs followed by inputs |
Default argument | Prohibited in principle | Allowed for use except for the cases described below:
|
File name | file_name.cc | FileName.cpp(file_name.cpp in the sample) |
#include guard | Also append #pragma once (for accelerating compilation in Visual Studio) | |
Use of boost | Not to be used by libraries (may be used for other purposes such as testing) | |
Accessor function name | get_xyz() / set_xyz() | GetXyz() / SetXyz() |
Argument passed by reference | Non-const references are prohibited | In nlib , non-cost references are allowed as exceptions in the following cases.
|
Use of C++11 | Ensure that headers and source code can be properly compiled also by using C++03 compilers.
| |
nullptr | Use if C++11 | In principle, don't use nullptr_t or nullptr as long as C++03 is used.
|
constexpr | Use if C++11 | For the time being, use of constexpr should be avoided except in obvious cases.
|
Comment |
|
--linelength=100
to allow up to 100 characters per line. cpplint
's legal/copyright
, build/include_alpha
, and whitespace/newline
categories have been suppressed. algorithm
header are not required when using std::swap
. nlib
supports checking source code using clang-check
. Generating a makefile with CMake creates a file called compile_commands.json
, which clang-check
uses to run. clang
manual.clang-format
to standardize the indentation and other stylistic aspects to suit your preferences. You can use the configuration used by nlib
, which is stored in a .clang-format
file (for clang
3.5) that is included in the nlib
package. It is recommended that you first convert your source code en masse using clang-format
, and then use cpplint.py
to do common detailed checks.pragma
warnings is permitted. _MSC_FULL_VER
in your code. gcc
and clang
binary packages available for Cygwin (32-bit) and Ubuntu. In general, resolve all warnings shown when using -Wall -Wextra. pragma
warnings is permitted. -Wstack-usage=65536
to ensure that the stack is not overused. -fstack-protector
. nlib
are ensuring that there are zero cpplint.py
warnings and that compilation and tests succeed in all environments.Platform.h
must appear within code that can be compiled in all environments it could conceivably be used in. That said, inclusion of code that is optimized for specific hardware using SIMD instructions or other such techniques is permitted. NLIB_FINAL
or NLIB_OVERRIDE
and typedef
s to safely incorporate C++11 features and continuously make it possible to port to C++11 or C++14. errno_t
type, as recommended by https://www.securecoding.cert.org/confluence/x/QgAy. nlib
) is written in a way that anticipates the use of these features, such as exception safety. malloc
and free
, use functions like nlib_malloc
and nlib_free
. new (std::nothrow)
for new
. new
operator must not be overloaded within the library. nlib_printf
are passed to Win32 API after conversion to UTF-16 in nlib
. Nflags
) is an exception. char
type must work correctly, whether signed or unsigned. signed char
. wchar_t
is 16-bit; UTF-32 is supported if wchar_t
is 32-bit. NLIB_WCHAR_SIZE
is defined as either 2 or 4, so you can use this to make the determination. nlib_utf16_t
as the type for UTF-16 characters, and use nlib_utf32_t
as the type for UTF-32 characters. typedef
as char16_t
and char32_t
, respectively. nlib_strcplen_ex
allows you to request the number of code points and byte length simultaneously while performing validation. If SIMD is supported, this operation can be sped up even more. NLIB_CXX11_RVALUE_REFERENCES
, and you must also define member functions like the following so that the same functionality can be implemented in C++03. boost::move
exist, but they cannot achieve full compatibility, so they are not used. type_traits
are used with care. This feature of C++11 is sometimes buggy or is not a complete implementation for some compilers or compiler versions. A tentative wrapper has been provided in nn/nlib/TypeTraits.h
, but only use it if there is no other alternative. NLIB_DISALLOW_COPY_AND_ASSIGN
instead. .h
format. There are two reasons for this. %<xxx.h%>
and %<cxxx%>
formats within nlib. (The %<xxx.h%>
format must be included because there is a requirement that nn/nlib/Platform.h
can be compiled with a C compiler.) testing
library can be used. gcc
, you can calculate test coverage automatically by using gcovr
. manual.h
files located within each include directory. English versions of the manual are stored as manual_en.h
. This approach allows multiple languages to be managed within the same repository. cmake/common.cmake
and cmake/import.nx_misc.cmake
, from CMakeLists.txt
. You can refer to samples/cmake/CMakeLists.txt
. nlib
, and their workarounds.nlib
uses new
(std::nothrow
) for memory allocation. When applications and other libraries overload new
or delete
, operator new(size_t, const std::nothrow_t&)
must also be overloaded. heap_replace_malloc
sample.nlib
does not use malloc
or free
directly. Instead, it uses functions like nlib_malloc
and nlib_free
. These functions are weakly defined, so they can be overridden by user-defined functions. heap_replace_malloc
sample.cmake/common.cmake.win32
within the package. Please reference them.MACRO_XXXX
using the command-line arguments to the compiler.nlib
. Writing acceptance tests for future use makes it easier to make this type of decision. However, only the latest version receives support. Note this fact.nlib
are permitted to restructure or repackage nlib
and to redistribute it, but only within the project.nlib_printf
must be encoded using UTF-8.nlib_int32_from_chars()
and nlib_double_from_chars()
. They belong to a group of functions that are assumed to wrap std::from_chars
of C++17. StringView
but not in std::string_view
have been deprecated. For those functions, implementation as new free functions is provided. msgpack::MpWalker::GetTimestamp()
and msgpack::MpDirectWriter::WriteTimestamp()
. msgpack::JsonStreamGenerator::Timestamp()
and msgpack::JsonStreamParser::ToTimestamp()
. msgpack::MpObject::InitTimeStamp()
and msgpack::MpObject::GetTimestamp()
. OSS
libraries to 3.20.0. msgpack::MpDirectWriter
. The class for directly writing MessagePack data into memory. UriQueryDecoder
and UriQueryEncoder
. msgpack::JsonStreamParser::Parse()
has encountered an error. nlib_bswap16()
, nlib_bswap32()
, and nlib_bswap64()
. swap()
member functions for various classes have been deprecated. The swap()
for free functions is defined with the standard means that uses move constructors and move assignment constructors. HttpStyleUri
and FileStyleUri
have been deprecated. Use Uri
, UriQueryDecoder
, and UriQueryEncoder
instead. msgpack::JsonSchemaValidator
and msgpack::JsonSchemaConverter
. They are classes for inspecting JSON based on http://json-schema.org/. DateTime::Parse()
now supports parsing strings that do not terminate with a null character. DateTime::IsRfc3339()
. Uri::Parse()
, HttpStyleUri::Parse()
, and FileStyleUri::Parse()
now support parsing strings that do not terminate with a null character. Uri::IsHostName()
. Uri::IsIpv4()
and Uri::IsIpv6()
. Uri::IsEmailAddress()
. Uri::IsUri()
and Uri::IsUriReference()
. UriTemplate::IsUriTemplate()
. msgpack::MpObject::IsJsonPointer()
. nlib_ticktime()
is now improved in Windows environments (by using QueryPerformanceCounter()). nlib_epochtime()
is now improved when running in Windows 10 environments (by using GetSystemTimePreciseAsFileTime()). nlib_barrier
is used. msgpack::MpObject::SwapMapItem()
and msgpack::MpObject::SwapArrayItem()
as deprecated. nlib_byte_t
type. In the future, this type will be defined as std::byte
using a typedef in C++17. kEnumName
in the future. Enumerator values in the format of ENUM_NAME
will no longer be allowed to be used. nlib_strcplen2
, nlib_popcnt(x)
, nlib_clz(x)
, and nlib_ctz(x)
macros that had been defined only for compatibility. Use nlib_strcplen
, nlib_popcnt32(x)
, nlib_clz32(x)
, and nlib_ctz32(x)
instead. msgpack::MpObject::Clone()
was changed to a const member function. msgpack::MpWalker
generated an error status when the end of a byte sequence was reached. msgpack::JsonPatch
class and the msgpack::JsonPatchBuilder
class. Those classes support JSON Patch(RFC 6902). simd::i128arg
unnecessarily represents a reference type. msgpack::GetMapItem()
, added an overload that can obtain MpObjectKv
using a non-null terminated string. /Ob1
option is now specified for a Debug build in Visual Studio. This change causes inline functions to be expanded. msgpack::MpObject::InsertArrayItem()
, msgpack::MpObject::RemoveArrayItem()
, and msgpack::MpObject::RemoveMapItem()
to the msgpack library. msgpack::MpObject::DigByJsonPointer()
and msgpack::MpObject::RemoveByJsonPointer()
to the msgpack library. This class supports JSON Pointer (RFC6901). msgpack::MpObject
. The operation evaluated that the values are different only when the key orders of MpObject
are different. msgpack::MpObject::ResolveJsonPointer()
to the msgpack library. This class supports JSON Pointer (RFC6901). nlib_utf16_t
and nlib_utf32_t
can now be defined with typedef
even when using C. nlib_utf8_t
type. utf16_t
and utf32_t
are now deprecated. These types will be deleted in a future release. msgpack::jsonrpc::JsonRpcRequest::Init()
determined a request to be invalid that no params
is specified for. © 2012-2017 Nintendo Co., Ltd. All rights reserved.