diff options
| -rw-r--r-- | DEVELOPING.md | 112 | ||||
| -rw-r--r-- | INSTALL.md | 7 | ||||
| -rw-r--r-- | platform/android/README.md | 7 | ||||
| -rw-r--r-- | platform/linux/README.md | 9 |
4 files changed, 128 insertions, 7 deletions
diff --git a/DEVELOPING.md b/DEVELOPING.md new file mode 100644 index 0000000000..c5c5c53f8a --- /dev/null +++ b/DEVELOPING.md @@ -0,0 +1,112 @@ +# Modern C++ support + +Mapbox GL Native supports the C++14 standard, and encourages contributions to +the source code using modern C++ idioms like return type deductions, generic +lambdas, `std::optional` and alike. However, we do not support all the features +from the final draft of the C++14 standard - we had to sacrifice support for +these features in order to support GCC from version 4.9 onwards. + +The following C++14 features are **not supported** in Mapbox GL Native: + +## [C++14 variable templates](https://isocpp.org/wiki/faq/cpp14-language#variable-templates) + +Constructs like the example below are not supported: + +```C++ +template<typename T> constexpr T pi = T(3.14); +``` + +### Workarounds: + +- If the variable is an alias, use the call the alias points to: [example](https://github.com/mapbox/mapbox-gl-native/commit/f1ac757bd28351fd57113a1e16f6c2e00ab193c1#diff-711ce10b54a522c948efc9030ffab4fcL269) +```C++ +// auto foo = pi<double>; +auto foo = double(3.14); +``` + +- Replace variable templates with either functions or structs: [example 1](https://github.com/mapbox/mapbox-gl-native/commit/f1ac757bd28351fd57113a1e16f6c2e00ab193c1#diff-ffbe6cdfd30513aaa4749b4d959a5da6L58), [example 2](https://github.com/mapbox/mapbox-gl-native/commit/f1ac757bd28351fd57113a1e16f6c2e00ab193c1#diff-04af54dc8685cdc382ebe24466dc1d00L98) + +## [C++14 aggregates with non-static data member initializers](http://en.cppreference.com/w/cpp/language/aggregate_initialization) + +Constructs like the example below are not supported: + +```C++ +struct Foo { + int x = { 0 }; +}; + +// error: no matching function for call to 'Foo::Foo(<brace-enclosed initializer list>)' +int main() { + Foo foo { 0 }; + return 0; +} +``` + +### Workarounds +- Replace data member initializers with default parameter values in default constructors: + +```C++ +struct Foo { + Foo(int x_ = 0) : x(x_) {} + int x; +}; + +int main() { + Foo foo { 0 }; // works with default constructor + return 0; +} +``` + +- Replace bracket initialization with regular round brackets or none: + +```C++ +struct Foo { + Foo(int x_ = 0) : x(x_) {} + int x; +}; + +int main() { + Foo foo(); // works + Foo bar; // also works + return 0; +} +``` + +## [Extended `constexpr` support](https://isocpp.org/wiki/faq/cpp14-language#extended-constexpr) + +GCC 4.9 strictly forbids `constexpr` usage in the following scenarios: +- No local variable declarations (not `static` or `thread_local`, and no uninitialized variables) +- Cannot mutate objects whose lifetime began with the constant expression evaluation +- Disable usage of if, switch, for, while, do-while (not goto) inside constexpr expressions +- Enforces that constexpr member functions are implicitly const + +```C++ +// sorry, unimplemented: use of the value of the object being constructed +// in a constant expression +struct Foo { + int x, y; + constexpr Foo(int i) : x(i), y(x) {} +}; + +// error: body of constexpr function 'constexpr int test1(int)' not a +// return-statement +constexpr int test1(int i) { + int j = i; + return j; +} + +// error: body of constexpr function 'constexpr bool test2(int)' not a +// return-statement +constexpr bool test2(int i) { + if (i > 0) { + return true; + } else { + return false; + } +} +``` + +### Workarounds + +- Either remove `constexpr` specifier or replace it with `inline` in case of + functions diff --git a/INSTALL.md b/INSTALL.md index 1c6c07f05f..61d2271de5 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -23,14 +23,17 @@ Clone the git repository: These dependencies are required for all operating systems and all platform targets. - - Modern C++ compiler that supports `-std=c++14` + - Modern C++ compiler that supports `-std=c++14`\* - clang++ 3.5 or later _or_ - - g++-5 or later + - g++-4.9 or later - [CMake](https://cmake.org/) 3.1 or later (for build only) - [cURL](https://curl.haxx.se) (for build only) - [Node.js](https://nodejs.org/) 4.2.1 or later (for build only) - [`pkg-config`](https://wiki.freedesktop.org/www/Software/pkg-config/) (for build only) +**Note**: We partially support C++14 because GCC 4.9 does not fully implement the +final draft of the C++14 standard. More information in [DEVELOPING.md](DEVELOPING.md). + Depending on your operating system and target, you'll need additional dependencies: diff --git a/platform/android/README.md b/platform/android/README.md index 7c28433d96..9b5029b8eb 100644 --- a/platform/android/README.md +++ b/platform/android/README.md @@ -40,13 +40,16 @@ These dependencies are required for all operating systems and all platform targe - NDK - LLDB -- Modern C++ compiler that supports -std=c++14 +- Modern C++ compiler that supports `-std=c++14`\* - clang++ 3.5 or later or - - g++-5 or later + - g++-4.9 or later - [cURL](https://curl.haxx.se) (for build only) - [Node.js](https://nodejs.org/) or later (for build only) - [pkg-config](https://wiki.freedesktop.org/www/Software/pkg-config/) (for build only) +**Note**: We partially support C++14 because GCC 4.9 does not fully implement the +final draft of the C++14 standard. More information in [DEVELOPING.md](DEVELOPING.md). + ##### Additional Dependencies for Linux _These instructions were tested on Ubuntu 16.04 LTS (aka Xenial Xerus)._ diff --git a/platform/linux/README.md b/platform/linux/README.md index b6a3b9a446..8b8ac9d089 100644 --- a/platform/linux/README.md +++ b/platform/linux/README.md @@ -8,12 +8,15 @@ This process gives you a Linux desktop app built on a Linux host system. ### Build -Install GCC 5+ if you are running Ubuntu 14.04 or older. Alternatively, you can also use [Clang 3.5+](http://llvm.org/apt/). +Install GCC 4.9+ if you are running Ubuntu 14.04 or older. Alternatively, you can also use [Clang 3.5+](http://llvm.org/apt/). sudo add-apt-repository --yes ppa:ubuntu-toolchain-r/test sudo apt-get update - sudo apt-get install gcc-5 g++-5 - export CXX=g++-5 + sudo apt-get install gcc-4.9 g++-4.9 + export CXX=g++-4.9 + +**Note**: We partially support C++14 because GCC 4.9 does not fully implement the +final draft of the C++14 standard. More information in [DEVELOPING.md](DEVELOPING.md). Ensure you have git and other build essentials: |