summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--DEVELOPING.md112
-rw-r--r--INSTALL.md7
-rw-r--r--platform/android/README.md7
-rw-r--r--platform/linux/README.md9
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: