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

[docs] Make per-platform installation docs self-contained

Browse Source 
I've seen several issues where users followed platform-specific install docs, but were unaware of additional prerequisites spelled out in the top-level INSTALL.md. So let's try making each platform's installation documentation self contained.
This commit is contained in:
John Firebaugh
2018-04-29 15:27:49 -07:00
parent 65a4ee2373
commit 9a4b806fa8
9 changed files with 88 additions and 95 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
INSTALL.md
View File

@@ -1,56 +1,15 @@
# Building & Developing Mapbox GL Native from Source
# Building & Developing from Source
**Just trying to use Mapbox GL Native? You don't need to read this stuff! We
**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/).**
Still with us? These are the instructions you'll need to build Mapbox GL Native
from source on a variety of platforms and set up a development environment.
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:
Your journey will start with installing dependencies, then getting the source code, and
then setting up a development environment, which varies depending on your
operating system and what platform you want to develop for.
## 1: Installing dependencies
### macOS
1. Install [Xcode](https://developer.apple.com/xcode/)
2. Launch Xcode and install any updates
3. Install [Homebrew](http://brew.sh)
4. Install [Node.js](https://nodejs.org/), [CMake](https://cmake.org/), and [ccache](https://ccache.samba.org) with `brew install nodejs cmake ccache`
5. Install [xcpretty](https://github.com/supermarin/xcpretty) with `[sudo] gem install xcpretty` (optional, used for prettifying command line builds)
### Linux
Install the following:
- `clang++` 3.5 or later or `g++` 4.9 or later
- [git](https://git-scm.com/)
- [CMake](https://cmake.org/) 3.1 or later
- [cURL](https://curl.haxx.se)
- [Node.js](https://nodejs.org/) 4.2.1 or later
- [`libcurl`](http://curl.haxx.se/libcurl/) (depends on OpenSSL)
- [ccache](https://ccache.samba.org) (optional, improves recompilation performance)
## 2: Getting the source
Clone the git repository:
git clone https://github.com/mapbox/mapbox-gl-native.git
cd mapbox-gl-native
## 3: Setting up a development environment & building
See the relevant SDK documentation for next steps:
* [Maps SDK for Android](platform/android/)
* [Maps SDK for iOS](platform/ios/)
* [Maps SDK for macOS](platform/macos/)
* [Maps SDK for Qt](platform/qt/)
* [Mapbox GL Native on Linux](platform/linux/)
* [node-mapbox-gl-native](platform/node/)
## 4: Keeping up to date
This repository uses Git submodules, which should be automatically checked out when you first run a `make` command for one of the above platforms. These submodules are not updated automatically and we recommended that you run `git submodule update` after pulling down new commits to this repository.
* [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)

6
platform/ios/DEVELOPING.md
View File

@@ -4,14 +4,10 @@ This document explains how to build the Mapbox Maps SDK for iOS from source. It
## Requirements
The Mapbox Maps SDK for iOS and iosapp demo application require iOS 9.0 or above.
The Mapbox Maps SDK for iOS requires Xcode 9.1 or above to compile from source.
See the "Requirements" section in [INSTALL.md](INSTALL.md).
## Building the SDK
Make sure that you have the [core dependencies](../../INSTALL.md) installed.
Create and open an Xcode workspace that includes both the SDK source and some Objective-C test applications by running:
```bash

26
platform/ios/INSTALL.md
View File

@@ -18,16 +18,34 @@ The Mapbox Maps SDK for iOS requires:
* Xcode 9.1 or higher to compile from source
* Xcode 8.0 or higher to integrate the compiled framework into an application
### Building the SDK
1. [Install core dependencies](../../INSTALL.md).
Before building, follow these steps to install prerequisites:
1. Install [Xcode](https://developer.apple.com/xcode/)
1. Launch Xcode and install any updates
1. Install [Homebrew](http://brew.sh)
1. Install [Node.js](https://nodejs.org/), [CMake](https://cmake.org/), and [ccache](https://ccache.samba.org):
```
brew install node cmake ccache
```
1. Install [xcpretty](https://github.com/supermarin/xcpretty) (optional, used for prettifying command line builds):
```
[sudo] gem install xcpretty
```
1. Install [jazzy](https://github.com/realm/jazzy) for generating API documentation:
```
[sudo] gem install jazzy
```
### Building the SDK
1. Clone the git repository:
```
git clone https://github.com/mapbox/mapbox-gl-native.git
cd mapbox-gl-native
```
Note that this repository uses Git submodules. They'll be automatically checked out when you first run a `make` command,
but are not updated automatically. We recommended that you run `git submodule update` after pulling down new commits to
this repository.
1. Run `make iframework BUILDTYPE=Release`. The packaging script will produce a `build/ios/pkg/` folder containing:
- a `dynamic` folder containing a dynamically-linked fat framework with debug symbols for devices and the iOS Simulator
- a `documentation` folder with HTML API documentation

20
platform/linux/README.md
View File

@@ -6,7 +6,7 @@ We are using Ubuntu for development. While the software should work on other dis
This process gives you a Linux desktop app built on a Linux host system.
### Build
### Prerequisites
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/).
@@ -15,9 +15,6 @@ Install GCC 4.9+ if you are running Ubuntu 14.04 or older. Alternatively, you ca
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:
sudo apt-get install curl git build-essential zlib1g-dev automake \
@@ -38,6 +35,21 @@ Install glfw3 dependencies:
x11proto-xf86vidmode-dev libxxf86vm-dev \
libxcursor-dev libxinerama-dev
[Node.js](https://nodejs.org/) 4.2.1 or later is also required.
[ccache](https://ccache.samba.org) is optional, but improves recompilation performance.
## Build
Clone the git repository:
git clone https://github.com/mapbox/mapbox-gl-native.git
cd mapbox-gl-native
Note that this repository uses Git submodules. They'll be automatically checked out when you first run a `make` command,
but are not updated automatically. We recommended that you run `git submodule update` after pulling down new commits to
this repository.
Set the environment variable `MAPBOX_ACCESS_TOKEN` to your [Mapbox access token](ACCESS_TOKEN.md):
export MAPBOX_ACCESS_TOKEN=MYTOKEN

16
platform/macos/DEVELOPING.md
View File

@@ -4,24 +4,10 @@ This document explains how to build the Mapbox Maps SDK for macOS from source. I
## Requirements
The Mapbox Maps SDK for macOS and the macosapp demo application run on macOS 10.10.0 or above.
The Mapbox Maps SDK for macOS requires Xcode 8.0 or above.
See the "Requirements" section in [INSTALL.md](INSTALL.md).
## Building the SDK
1. [Install core dependencies](../../INSTALL.md).
1. Run `make xproj`.
1. Switch to the “dynamic” or “macosapp” scheme. The former builds just the Cocoa framework, while the latter also builds a Cocoa demo application based on it.
### Packaging builds
Install [jazzy](https://github.com/realm/jazzy) for generating API documentation:
```bash
[sudo] gem install jazzy
```
Build and package the SDK by using one of the following commands:
* `make xpackage` builds a dynamic framework in the Debug configuration, including debug symbols.

36
platform/macos/INSTALL.md
View File

@@ -6,19 +6,41 @@ This document explains how to build a development version of the Mapbox Maps SDK
The Mapbox Maps SDK for macOS requires the macOS 10.10.0 SDK (or above) and Xcode 8.0 (or above). To use this SDK with Xcode 7.3.1, download and use a symbols build from the [releases](https://github.com/mapbox/mapbox-gl-native/releases) page.
### Building the SDK from source
To build the SDK from source:
1. [Install core dependencies](../../INSTALL.md).
Before building, follow these steps to install prerequisites:
1. Install [Xcode](https://developer.apple.com/xcode/)
1. Launch Xcode and install any updates
1. Install [Homebrew](http://brew.sh)
1. Install [Node.js](https://nodejs.org/), [CMake](https://cmake.org/), and [ccache](https://ccache.samba.org):
```
brew install node cmake ccache
```
1. Install [xcpretty](https://github.com/supermarin/xcpretty) (optional, used for prettifying command line builds):
```
[sudo] gem install xcpretty
```
1. Install [jazzy](https://github.com/realm/jazzy) for generating API documentation:
```
[sudo] gem install jazzy
```
1. Run `make xpackage`, which produces a `Mapbox.framework` in the `build/macos/pkg/` folder.
### Building the SDK from source
To build the SDK from source:
1. Clone the git repository:
```
git clone https://github.com/mapbox/mapbox-gl-native.git
cd mapbox-gl-native
```
Note that this repository uses Git submodules. They'll be automatically checked out when you first run a `make` command,
but are not updated automatically. We recommended that you run `git submodule update` after pulling down new commits to
this repository.
1. Run:
```
make xpackage
```
This produces a `Mapbox.framework` in the `build/macos/pkg/` folder.
### Installation

8
platform/node/DEVELOPING.md
View File

@@ -4,12 +4,14 @@ This document explains how to build the [Node.js](https://nodejs.org/) bindings
## Building
To develop these bindings, you’ll need to build them from source. Building requires [installing all of the basic dependencies needed for Mapbox GL Native](../../INSTALL.md), then running:
To develop these bindings, you’ll need to build them from source. Building requires the prerequisites listed in either
the [macOS](../macos/INSTALL.md#requirements) or [Linux](../linux/README.md#prerequisites) install documentation, depending
on the target platform.
To compile the Node.js bindings and install module dependencies, from the repository root directory, run:
npm install --build-from-source
From the root directory. This will compile the Node.js bindings and install module dependencies.
To recompile just the C++ code while developing, run `make node`.
To create an Xcode project and use a GUI debugger in the case of a crash, run `make xnode`.

3
platform/node/README.md
View File

@@ -17,7 +17,8 @@ Run:
npm install @mapbox/mapbox-gl-native
```
Other platforms will fall back to a source compile with `make node`; see INSTALL.md in the repository root directory for prequisites.
Other platforms will fall back to a source compile with `make node`; see [DEVELOPING.md](DEVELOPING.md) for details on
building from source.
## Testing

7
platform/qt/README.md
View File

@@ -17,9 +17,7 @@ See the Mapbox Qt landing page for more details: https://www.mapbox.com/qt/
#### Linux
For Linux (tested on Ubuntu) desktop, together with these [build
instructions](https://github.com/mapbox/mapbox-gl-native/tree/master/platform/linux#build),
you also need:
For Linux (tested on Ubuntu) desktop, together with these [build instructions](../linux/README.md), you also need:
```
$ sudo apt-get install qt5-default
@@ -55,8 +53,7 @@ At runtime, you will also need installed:
### Build instructions
Public API headers
can be found in the [platform/qt/include](https://github.com/mapbox/mapbox-gl-native/tree/master/platform/qt/include) directory.
Public API headers can be found in the [platform/qt/include](qt/include) directory.
#### Linux and macOS