tei/MapLibreParticleLab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[documentation] Updated README and DEVELOPING

Browse Source 
To reflect changes in the buildsystem.
This commit is contained in:
Thiago Marcos P. Santos
2020-02-07 18:57:44 +02:00
parent 021e48f35e
commit 97cab6365b
3 changed files with 27 additions and 211 deletions
Download Patch File Download Diff File Expand all files Collapse all files

175
DEVELOPING.md
View File

@@ -1,168 +1,11 @@
# Modern C++ support
# Developing
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.
This is been rewritten to include:
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
## [Polymorphic lambdas](https://gcc.gnu.org/bugzilla/show_bug.cgi?id=68278)
GCC 5.2.0 crashes with polymorphic lambdas and this version of the compiler
is currently used in Qt Automotive. Luckily polymorphic lambdas are rarely
used/needed but we had one incident fixed by #9665.
### Workarounds
- Copy & Paste™ the code.
## [Inheriting Constructors](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2540.htm)
Compilers with only partial C++11 support causes compilation errors when using-declaration is used in derived class to inherit its base class's constructors `(e.g. using Base::Base;)`.
```C++
#include <vector>
template <typename T>
struct Varargs : std::vector<T>
{
using std::vector<T>::vector;
};
// error: conflicts with version inherited from 'std::__1::vector<int, std::__1::allocator<int> >'
int main()
{
Varargs<int> v;
return 0;
}
```
### Workarounds
- Replace using-declaration (e.g. using Base::Base;) in derived class with `universal forwarding constructor`.
```C++
#include <vector>
template <typename T>
struct Varargs : std::vector<T>
{
template <class... Args>
Varargs(Args&&... args) : std::vector<T>(std::forward<Args>(args)...) {}
};
int main()
{
Varargs<int> v;
return 0;
}
```
Note: Using `universal forwarding constructor` may not be appropriate when derived class has additional members that are not in base class. Write constructors for the derived class explicitly instead of using `universal forwarding constructor` when the derived class has additional members.
- How to build for the platforms we support.
- Acceptance criteria for code contributions (style, static asserts)
- How to run the unit tests.
- How to run the benchmarks.
- How to run the render tests.
- How to rebaseline baselines metrics.
- How to use GL Native as a 3rd party library in your project.

15
INSTALL.md
View File

@@ -1,15 +0,0 @@
# Building & Developing from Source
**Just trying to use one of the Mapbox Maps SDKs? You don't need to read this stuff! We
provide [easy-to-install, prebuilt versions of the Mapbox Maps SDKs for iOS and Android
that you can download instantly and get started with fast](https://www.mapbox.com/install/).**
If you're certain you need to build from source, rather than using a prebuilt SDK, please
refer to the installation instructions for the platform of interest:
* [Mapbox Maps SDK for Android](platform/android/README.md)
* [Mapbox Maps SDK for iOS](platform/ios/INSTALL.md)
* [Mapbox Maps SDK for macOS](platform/macos/INSTALL.md)
* [Mapbox Maps SDK for Qt](platform/qt/README.md)
* [Mapbox GL Native on Linux](platform/linux/README.md)
* [node-mapbox-gl-native](platform/node/DEVELOPING.md)

48
README.md
View File

@@ -1,42 +1,30 @@
# Mapbox GL Native
[![Circle CI build status](https://circleci.com/gh/mapbox/mapbox-gl-native.svg?style=shield)](https://circleci.com/gh/mapbox/workflows/mapbox-gl-native/tree/master) [![Coverage Status](https://codecov.io/gh/mapbox/mapbox-gl-native/branch/master/graph/badge.svg)](https://codecov.io/gh/mapbox/mapbox-gl-native)
A library for embedding interactive, customizable vector maps into native applications on multiple platforms. It
takes stylesheets that conform to the [Mapbox Style Specification](https://github.com/mapbox/mapbox-gl-style-spec/),
applies them to vector tiles that conform to the [Mapbox Vector Tile Specification](https://github.com/mapbox/vector-tile-spec),
and renders them using OpenGL. [Mapbox GL JS](https://github.com/mapbox/mapbox-gl-js) is the WebGL-based counterpart,
and renders them using OpenGL or Metal. [Mapbox GL JS](https://github.com/mapbox/mapbox-gl-js) is the WebGL-based counterpart,
designed for use on the Web.
| SDK | Languages | Build status |
| --------------------------------------------------- | ---------------------------------- | ---------------------------------------- |
| Mapbox GL Native Core | C++14 | [![Circle CI build status](https://circleci.com/gh/mapbox/mapbox-gl-native.svg?style=shield)](https://circleci.com/gh/mapbox/workflows/mapbox-gl-native/tree/master) [![Coverage Status](https://codecov.io/gh/mapbox/mapbox-gl-native/branch/master/graph/badge.svg)](https://codecov.io/gh/mapbox/mapbox-gl-native) |
| [Mapbox Maps SDK for Android](../platform/android/) | Java | [![Circle CI build status](https://circleci.com/gh/mapbox/mapbox-gl-native.svg?style=shield)](https://circleci.com/gh/mapbox/workflows/mapbox-gl-native/tree/master) |
| [Mapbox Maps SDK for iOS](../platform/ios/) | Objective-C or Swift | [![Circle CI build status](https://circleci.com/gh/mapbox/mapbox-gl-native.svg?style=shield)](https://circleci.com/gh/mapbox/workflows/mapbox-gl-native/tree/master) |
| [Mapbox Maps SDK for macOS](../platform/macos/) | Objective-C, Swift, or AppleScript | [![Circle CI build status](https://circleci.com/gh/mapbox/mapbox-gl-native.svg?style=shield)](https://circleci.com/gh/mapbox/workflows/mapbox-gl-native/tree/master) |
| [node-mapbox-gl-native](../platform/node/) | Node.js | [![Circle CI build status](https://circleci.com/gh/mapbox/mapbox-gl-native.svg?style=shield)](https://circleci.com/gh/mapbox/workflows/mapbox-gl-native/tree/master) |
| [Mapbox Maps SDK for Qt](../platform/qt) | C++03 | [![Circle CI build status](https://circleci.com/gh/mapbox/mapbox-gl-native.svg?style=shield)](https://circleci.com/gh/mapbox/workflows/mapbox-gl-native/tree/master) [![AppVeyor CI build status](https://ci.appveyor.com/api/projects/status/3q12kbcooc6df8uc?svg=true)](https://ci.appveyor.com/project/Mapbox/mapbox-gl-native) |
## [Developing](DEVELOPING.md)
[Additional Mapbox GL Native–based libraries](https://wiki.openstreetmap.org/wiki/Mapbox_GL#Libraries) for **hybrid applications** are developed outside of this repository. If your platform or hybrid application framework isn’t listed there, consider embedding [Mapbox GL JS](https://github.com/mapbox/mapbox-gl-js) using the standard Web capabilities on your platform.
We use [CMake](https://cmake.org/cmake/help/latest/) to build Mapbox GL Native
for various platforms, including Linux, Android, iOS, macOS and Windows. The
following command, executed from the root of this repository tree, will build
Mapbox GL Native targeting your host architecture given that you have all the
dependencies installed and run the example app.
```
$ git update submodules --init --recursive
$ cmake . -B build
$ cmake --build build
$ MAPBOX_ACCESS_TOKEN=my_access_token_here ./build/platform/glfw/mbgl-glfw
```
## License
Mapbox GL Native is licensed under the [3-Clause BSD license](../LICENSE.md).
Mapbox GL Native is licensed under the [2-Clause BSD license](LICENSE.md). The licenses of its dependencies are tracked via [FOSSA](https://app.fossa.io/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fmapbox%2Fmapbox-gl-native):
## Developing
The `next` directory contains the next generation buildsystem for Mapbox GL Native, based solely on CMake with the
goal of minimizing the use of scripts, increase portability and support building Mapbox GL Native as a subdirectory
of another CMake project. This new buildsystem is also designed to build offline, making use of pre-installed and
vendorized dependencies. When using the build bot docker image, the build should produce the exact same results as
the bots, making it a hermetically sealed build for Linux, Qt and Android.
### Building and running tests
The following command, executed from the root of this repository tree, will build Mapbox GL Native targeting your
host architecture given that you have all the dependencies installed.
```
$ mkdir build && cd build
$ cmake ..
$ make -j8
$ make test ARGS=-V
```
[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fmapbox%2Fmapbox-gl-native.svg?type=large)](https://app.fossa.io/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fmapbox%2Fmapbox-gl-native)