From 2729dcc06dd50df26fd46a4dbbd1407ebf1313a2 Mon Sep 17 00:00:00 2001 From: Ilya Zverev Date: Thu, 24 Sep 2015 19:00:20 +0300 Subject: [PATCH 01/13] Initial versions of readme and license --- LICENSE | 202 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ NOTICE | 20 ++++++ README.md | 68 ++++++++++++++++++ 3 files changed, 290 insertions(+) create mode 100644 LICENSE create mode 100644 NOTICE create mode 100644 README.md diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000000..d645695673 --- /dev/null +++ b/LICENSE @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/NOTICE b/NOTICE new file mode 100644 index 0000000000..d82a32eba6 --- /dev/null +++ b/NOTICE @@ -0,0 +1,20 @@ +Copyright 2011-2015 MAPS.ME + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + +Most libraries in `3party` directory and in some others are made +by other people and organizations and licensed in different ways: +refer to their LICENCE, COPYING or NOTICE files for terms of use. + +All images and media content are Copyright (C) 2011-2015 MAPS.ME, +published under CC-BY 4.0 license. diff --git a/README.md b/README.md new file mode 100644 index 0000000000..520c548231 --- /dev/null +++ b/README.md @@ -0,0 +1,68 @@ +# MAPS.ME + +http://maps.me + +This is an application for [Android](https://play.google.com/store/apps/details?id=com.mapswithme.maps.pro) +and [iOS](https://itunes.apple.com/app/id510623322) devices for offline maps built from OpenStreetMap data. + +## Compilation + +You will need Qt 5.3 or later to build the project. On Mac OS X systems we recommend installing +XCode and [Homebrew](http://brew.sh/). See `build_omim.sh` script in `tools/unix` directory: +it builds debug and release versions of the desktop application and map generator tool, as well +as routing backend. + +For detailed installation instructions and Android/iOS building process, +see [INSTALL.md](https://github.com/mapsme/omim/tree/master/docs/INSTALL.md). + +Nightly builds for Android and iOS are published to [osmz.ru](http://osmz.ru/mwm/) +and Dropbox: [release](http://maps.me/release), [debug](http://maps.me/debug). + +## Building maps + +To create one or many map files, first build the project, then use `generate_mwm.sh` script from +`tools/unix` to create a single mwm file from pbf/o5m/bz2 source, or `generate_planet.sh` +to generate multiple countries at once from a planet o5m file. See detailed instructions +in [MWM.md](https://github.com/mapsme/omim/tree/master/docs/MWM.md). + +## Map styles + +MAPS.ME uses its own binary format for map styles, `drules_proto.bin`, which is compiled from +[MapCSS](http://wiki.openstreetmap.org/wiki/MapCSS) using modified Kothic library. +Feature set in MWM files depends on a compiled style, so make sure to rebuild maps after +releasing a style. + +For development, use MAPS.ME Designer app along with its generator tool: these allow +for quick rebuilding of a style and symbols, and for producing a zoom-independent +feature set in MWM files. + +See [STYLES.md](https://github.com/mapsme/omim/tree/master/docs/STYLES.md) for the +format description, instructions on building a style and some links. + +## Development + +You would need Qt 5 for development, most other libraries are included into the +repository, see `3party` directory. After cloning, the repository must be +initialized with `configure.sh`. The team uses mostly XCode and Qt Creator, +though these are not mandatory. We have an established +[coding style](https://github.com/mapsme/omim/blob/master/docs/cpp_coding_standard.txt). +Our pull request review process may be intimidating, but it ensures a consistent +code quality. + +All contributors must sign a [Contributor Agreement](https://github.com/mapsme/omim/blob/master/docs/CLA.md), +so both ours and theirs rights are protected. + +See [CONTRIBUTING.md](https://github.com/mapsme/omim/blob/master/docs/CONTRIBUTING.md) +for the repository initialization process, the description of all the directories +of this repository and other development-related information. + +## Feedback + +Please report bugs and suggestions to [the issue tracker](https://github.com/mapsme/omim/issues), +or by mail to bugs@maps.me. + +## Authors and License + +This source code is Copyright (C) 2011-2015 MAPS.ME, published under Apache Public License 2.0, +except third-party libraries. See [NOTICE](https://github.com/mapsme/omim/blob/master/NOTICE) +file for more information. From a67392b469cc50ebe9cf536cb2070ae95f9ccf7b Mon Sep 17 00:00:00 2001 From: Ilya Zverev Date: Fri, 25 Sep 2015 20:29:29 +0300 Subject: [PATCH 02/13] [docs] Documentation files, empty for now --- docs/CLA.md | 6 ++++++ docs/CONTRIBUTING.md | 15 +++++++++++++++ docs/INSTALL.md | 11 +++++++++++ docs/MWM.md | 11 +++++++++++ docs/STYLES.md | 15 +++++++++++++++ 5 files changed, 58 insertions(+) create mode 100644 docs/CLA.md create mode 100644 docs/CONTRIBUTING.md create mode 100644 docs/INSTALL.md create mode 100644 docs/MWM.md create mode 100644 docs/STYLES.md diff --git a/docs/CLA.md b/docs/CLA.md new file mode 100644 index 0000000000..f54f064b0c --- /dev/null +++ b/docs/CLA.md @@ -0,0 +1,6 @@ +# Contributor License Agreement + +To participate in MAPS.ME development, you need to sign an agreement, which +enforces your and our rights to the code. + +*todo* diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000000..ddc45ec342 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,15 @@ +# MAPS.ME Development + +## Initializing the Repository + +## Setting up IDE + +### Qt Creator + +### XCode + +## Coding Style + +## Directories + +## Pull Requests diff --git a/docs/INSTALL.md b/docs/INSTALL.md new file mode 100644 index 0000000000..eb03596ccb --- /dev/null +++ b/docs/INSTALL.md @@ -0,0 +1,11 @@ +# Building and Installing MAPS.ME + +## Desktop + +## Maps Generator + +### OSRM Backend + +## Android + +## iOS diff --git a/docs/MWM.md b/docs/MWM.md new file mode 100644 index 0000000000..2fd12a2b95 --- /dev/null +++ b/docs/MWM.md @@ -0,0 +1,11 @@ +# MWM Files + +## Building + +### Single region + +### Part of a planet + +### Testing + +## Format diff --git a/docs/STYLES.md b/docs/STYLES.md new file mode 100644 index 0000000000..66a013f285 --- /dev/null +++ b/docs/STYLES.md @@ -0,0 +1,15 @@ +# Styling MAPS.ME + +## MapCSS Source + +### Symbols + +## Compiling Styles + +## Designer Tool + +## UI Resources + +### Android + +### iOS From 8ee5431c242a9d1b5c43d3c8e9c31f7fe861c1d6 Mon Sep 17 00:00:00 2001 From: Ilya Zverev Date: Mon, 28 Sep 2015 21:26:29 +0300 Subject: [PATCH 03/13] [docs] More building and installing --- docs/CONTRIBUTING.md | 46 ++++++++++++++++++ docs/INSTALL.md | 113 ++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 158 insertions(+), 1 deletion(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index ddc45ec342..43a8696c79 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -2,14 +2,60 @@ ## Initializing the Repository +The repository needs a lot of header and configuration files with private keys and such. +To initialize, run `configure.sh` from its root, and press "Enter" when asked for a +repository. The script will create two files, `private.h` and `android/secure.properties`, +which are required for compiling the project. If you have a private repository with +these files (and some other, like private keystores), pass the link like this: + + echo git@repository:org/omim-private.git | ./configure.sh + +Without keys, downloading of maps won't work, as well as statistics and online routing +assisting. For android, you would need private keys to build a release version (but +a debug one can be built without keys). + ## Setting up IDE +See [INSTALL.md](INSTALL.md) for command-line compilation instructions. + +* Install XCode and Command Line Tools, then run XCode and click "I Agree". + ### Qt Creator +* Download [Qt Creator](http://www.qt.io/download-open-source/) with Qt 5. +* In `Qt/5.5/clang_64/mkspecs/qdevice.pri` replace `10.10` with `10.11`, and + add a line `QMAKE_MAC_SDK = macosx10.11` (see installed versions in + `/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/`) +* Start Qt Creator, open `omim.pro`, choose "qt" target and run the project. +* To build the project faster, open "Project Settings", find "Build Steps", then + "Make Arguments" and put "-j8" there (without quotes). + +Debugging may not work in Qt Creator. To enable it, try creating a Build & Run kit in +preferences with XCode's lldb as a debugger and a clang compiler. + ### XCode +* Install [Homebrew](http://brew.sh/) and run `brew install qt5`. +* Run XCode, open `xcode/omim.xcworkspace`. +* Select "MapsMe" scheme and run the product. + ## Coding Style ## Directories +### Sources + +* **anim** - core animation controller. +* **api** - external API of the application. +* **base** - + +*todo* + +### Other + +* **3party** - external libraries, sometimes modified. +* **android** - Android UI + +*todo* + ## Pull Requests diff --git a/docs/INSTALL.md b/docs/INSTALL.md index eb03596ccb..4884770c10 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -1,11 +1,122 @@ -# Building and Installing MAPS.ME +# Building MAPS.ME + +First, do not forget to initialize a cloned repository, see +[CONTRIBUTING.md](CONTRIBUTING.md). ## Desktop +You would need Boost and Qt 5. With that, just run `omim/tools/unix/build_omim.sh`. +It will build both debug and release versions to `omim/../omim-build-`, as +well as OSRM backend for generating maps. Command-line switches are: + +* `-r` to build a release version +* `-d` to build a debug version +* `-o` to build OSRM backend +* `-c` to delete target directories before building + +To build a generator tool only, set `CONFIG=gtool` flag. To skip building tests, +use `CONFIG=no-tests`. + +When using a lot of maps, increase open files limit, which is only 256 on Mac OS X. +Use `ulimit -n 2000`, put it into `~/.bash_profile` to apply it to all new sessions. +In OS X to increase this limit globally, add `limit maxfiles 2048 2048` to `/etc/launchd.conf` +and run + + echo 'ulimit -n 2048' | sudo tee -a /etc/profile + +### Ubuntu 14.04 + +Install Qt 5.4: + + sudo add-apt-repository ppa:beineri/opt-qt542-trusty + sudo apt-get update + sudo apt-get install qt54base + source /opt/qt54/bin/qt54-env.sh + +To run OSRM binaries, you'll need: + + sudo apt-get install libtbb2 libluabind0.9.1 liblua50 libstxxl1 + +Do a git clone: + + git clone git@github.com:mapsme/omim.git + cd omim + ./configure.sh + +Then: + + sudo apt-get install clang-3.5 libboost-iostreams-dev libglu1-mesa-dev + sudo apt-get install libtbb-dev libluabind-dev libstxxl-dev libosmpbf-dev libprotobuf-dev + sudo ln -s /usr/lib/llvm-3.5/bin/clang /usr/bin/clang + sudo ln -s /usr/lib/llvm-3.5/bin/clang++ /usr/bin/clang++ + omim/tools/unix/build_omim.sh + +### Windows + +We haven't compiled MAPS.ME on Windows in a long time, though it is possible. It is likely +some make files should be updated. If you succeed, please submit a tutorial. + +### Download maps + +http://direct.mapswithme.com/direct/ + ## Maps Generator ### OSRM Backend +## Designer Tool + +The designer tool resides in a branch `map-style-editor-new`. You would need +to check it out before following these steps. + +### Building data + +* Run `CONFIG="gtool map-designer" omim/tools/unix/build_omim.sh`. +* Generate data as usual (either with `generate_mwm.sh` or `generate_planet.sh`). +* For MAPS.ME employees, publish planet data to http://designer.mapswithme.com/mac/DATA_VERSION +(via a ticket to admins, from `mapsme4:/opt/mapsme/designers`). + +### Building the tool + +* Run `omim/tools/unix/build_designer.sh DATA_VER APP_VER`, where `DATA_VER` is the +latest data version published to `designer.mapswithme.com` (e.g. `150912`), and +`APP_VER` is an application version, e.g. `1.2.3`. +* If you got "hdiutil -5341" error, you would need to build a dmg package yourself: +find a line with `hdiutil` in the script, copy it to a console, and if needed, increase +`-size` argument value. +* The resulting dmg package will be put into `omim/out`. + ## Android +* Install [Android SDK](https://developer.android.com/sdk/index.html) and +[NDK](https://developer.android.com/tools/sdk/ndk/index.html), place these somewhere +easy to type. + +* Go to `omim/tools/android` and run `./set_up_android.py`. It would ask for absolute paths +to SDK and NDK. Or specify these in command line: + + --sdk /Users/yourusername/Library/Android/sdk \ + --ndk /Users/yourusername/Library/Android/android-ndk-r10d + +* Go to `omim/android` and run `./gradlew clean assembleWebRelease`. + * There are `Release`, `Beta` and `Debug` builds. + * `assemble` produces apk files in `build/outputs/apk`, `install` installs one + on a connected device, and `run` immediately starts it. + * `Web` creates a full apk with World files, `Google` builds a store version + without these, and there are also `Amazon`, `Samsung`, `Xiaomi`, `Yandex` + and other targets. + +* If you encounter errors, try updating your Android SDK: + * In [SDK Manager](http://developer.android.com/tools/help/sdk-manager.html) + (for Android Studio: Tools → Android → SDK Manager) enable fresh + _build-tools_ and click on "Install packages..." + * In command line, go to `android-sdk/tools`, then + * `./android list sdk` for a list of packages to update. + * `./android update sdk --no-ui --filter 1,2,3` to update chosen packages. + +* To enable logging in case of crashes, after installing a debug version, run: + adb shell pm grant com.mapswithme.maps.pro.debug android.permission.READ_LOGS + After a crash, go to "Menu → Settings → Report a bug" and enter your e-mail to + receive a log file. + ## iOS From e3274547d4de122d6b412ea8ae72eb34ac5615da Mon Sep 17 00:00:00 2001 From: Ilya Zverev Date: Mon, 28 Sep 2015 22:38:05 +0300 Subject: [PATCH 04/13] [docs] Notify about submodules --- README.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 520c548231..23ff81e3af 100644 --- a/README.md +++ b/README.md @@ -5,12 +5,16 @@ http://maps.me This is an application for [Android](https://play.google.com/store/apps/details?id=com.mapswithme.maps.pro) and [iOS](https://itunes.apple.com/app/id510623322) devices for offline maps built from OpenStreetMap data. +## Submodules + +This repository contains submodules. Clone it with `git clone --recursive`. If you forgot, +run `git submodule update --init --recursive`. + ## Compilation -You will need Qt 5.3 or later to build the project. On Mac OS X systems we recommend installing -XCode and [Homebrew](http://brew.sh/). See `build_omim.sh` script in `tools/unix` directory: -it builds debug and release versions of the desktop application and map generator tool, as well -as routing backend. +To compile the project, you would need to initialize private key files. Run +`configure.sh` and press Enter to create empty files, good enough to build desktop +and Android debug packages. For detailed installation instructions and Android/iOS building process, see [INSTALL.md](https://github.com/mapsme/omim/tree/master/docs/INSTALL.md). @@ -42,8 +46,7 @@ format description, instructions on building a style and some links. ## Development You would need Qt 5 for development, most other libraries are included into the -repository, see `3party` directory. After cloning, the repository must be -initialized with `configure.sh`. The team uses mostly XCode and Qt Creator, +repository, see `3party` directory. The team uses mostly XCode and Qt Creator, though these are not mandatory. We have an established [coding style](https://github.com/mapsme/omim/blob/master/docs/cpp_coding_standard.txt). Our pull request review process may be intimidating, but it ensures a consistent From 5c31d7973db83d82e98cbe7fbaffc5ca4f3a07aa Mon Sep 17 00:00:00 2001 From: Ilya Zverev Date: Mon, 28 Sep 2015 22:54:17 +0300 Subject: [PATCH 05/13] [docs] Formatted cpp coding style to markdown --- README.md | 2 +- docs/CONTRIBUTING.md | 2 + .../{cpp_coding_standard.txt => CPP_STYLE.md} | 70 ++++++++++--------- 3 files changed, 41 insertions(+), 33 deletions(-) rename docs/{cpp_coding_standard.txt => CPP_STYLE.md} (57%) diff --git a/README.md b/README.md index 23ff81e3af..ef07618c2d 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,7 @@ format description, instructions on building a style and some links. You would need Qt 5 for development, most other libraries are included into the repository, see `3party` directory. The team uses mostly XCode and Qt Creator, though these are not mandatory. We have an established -[coding style](https://github.com/mapsme/omim/blob/master/docs/cpp_coding_standard.txt). +[coding style](https://github.com/mapsme/omim/blob/master/docs/CPP_STYLE.md). Our pull request review process may be intimidating, but it ensures a consistent code quality. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 43a8696c79..4c859d5051 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -41,6 +41,8 @@ preferences with XCode's lldb as a debugger and a clang compiler. ## Coding Style +See [CPP_STYLE.md](CPP_STYLE.md). + ## Directories ### Sources diff --git a/docs/cpp_coding_standard.txt b/docs/CPP_STYLE.md similarity index 57% rename from docs/cpp_coding_standard.txt rename to docs/CPP_STYLE.md index fa7bf65a71..44f3c8768c 100644 --- a/docs/cpp_coding_standard.txt +++ b/docs/CPP_STYLE.md @@ -1,13 +1,15 @@ -We write code without warnings! +# C++ Style Guide -In general, Google's coding standard http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml is used and we strongly encourage to read it. +**We write code without warnings!** + +In general, [Google's coding standard](http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml) is used, and we strongly encourage to read it. Below are our specific (but not all!) exceptions to the Google's coding standard: -- We use .cpp and .hpp files, not .cc and .h (.c and .h are used for C code), in UTF-8 encoding -- File names are lowercase with underscores, like file_reader.cpp -- We use #pragma once instead of the #define Guard in header files. -- We don't include system, std and boost headers directly, use #include "../std/" +- We use `.cpp` and `.hpp` files, not `.cc` and `.h` (`.c` and `.h` are used for C code), in UTF-8 encoding +- File names are lowercase with underscores, like `file_reader.cpp` +- We use `#pragma once` instead of the `#define` Guard in header files. +- We don't include system, std and boost headers directly, use `#include "../std/"` - We ARE using C++ exceptions - We are using all features of C++11 (the only known exception is thread_local which is not fully supported on all platforms) - We don't use boost libraries which require linking (and prefer C++11 types over their boost counterparts) @@ -17,15 +19,17 @@ Naming and formatting - We ALWAYS use two spaces indent and don't use tabs - We don't have hardcoded line width, but keep it reasonable to fit on the screen - Doxygen-style comments can be used -- Underscores are allowed only in prefixes for member variables and namespace names, like int m_countriesCount; namespace utf_parser -- Don't specify std:: and boost:: prefixes (headers in std/ folder already have 'using std::string') -- Use right-to-left order for variables/params: string const & s (reference to the const string) -- In one line 'if', 'for', 'while' we do not use brackets. If one line 'for' or 'while' is combined with one line 'if' do use brackets for cycle. -- Space after the keyword in conditions and loops. Space after ';' in for loop -- Space between binary operators, but can skip according to operators priority: x = y*y + z*z; +- Underscores are allowed only in prefixes for member variables and namespace names, like `int m_countriesCount; namespace utf_parser` +- Don't specify `std::` and `boost::` prefixes (headers in std/ folder already have `using std::string`) +- Use right-to-left order for variables/params: `string const & s` (reference to the const string) +- In one line `if`, `for`, `while` we do not use brackets. If one line `for` or `while` is combined with one line `if`, do use brackets for cycle. +- Space after the keyword in conditions and loops. Space after `;` in `for` loop +- Space between binary operators, but can skip according to operators priority: `x = y*y + z*z` - Space after double dash -// *********** Formatting Example/Guide/Reference *********** +## Formatting Example/Guide/Reference + +```cpp #include "../std/math.hpp" typedef double TMyTypeStartsWithCapitalTLetter; @@ -160,9 +164,9 @@ v = w*x + y/z; v = w * (x + z); // space after double dash +``` - -Tips and Hints +## Tips and Hints - If you see outdated code which can be improved - DO IT NOW (but in the separate pull request)! Make this awesome world even more better! - Your code should work at least on [mac|win|linux|android][x86|x86_64], [ios|android][armv7|arm64] architectures @@ -173,20 +177,22 @@ Tips and Hints - Ask your team if you have any questions - Use dev@maps.me mailing list to ask all developers and bugs@maps.me mailing list to post bugs - Release builds contain debugging information (for profiling), production builds are not -- If you don't have enough time to make it right, leave a '// TODO(DeveloperName): need to fix it' comment -- Some useful macroses: --- #ifdef DEBUG | RELEASE | OMIM_PRODUCTION --- #ifdef OMIM_OS_ANDROID | OMIM_OS_IPHONE | OMIM_OS_MAC (and some other useful OS-related macroses, see std/target_os.hpp) --- Use ASSERT(expression, (out message)) and ASSERT_XXXXXX macroses often to check code validity in DEBUG builds --- Use CHECK(expression, (out message)) and CHECK_XXXXXX macroses to check code validity in all builds --- Use LOG(level, (message)) for logging, below is more detailed description for level: - LINFO - always prints log message - LDEBUG - logs only in DEBUG - LWARNING - the same as LINFO but catches your attention - LERROR - the same as LWARNING, but crashes in DEBUG and works in RELEASE - LCRITICAL - the same as LERROR and ALWAYS crashes --- Need scope guard? Check MY_SCOPE_GUARD(name, func) --- Use std::array::size() to calculate plain C-array's size --- Declare your own exceptions with DECLARE_EXCEPTION(name, baseException), where baseException is usually RootException --- Throw exceptions with MYTHROW(exceptionName, (message)) --- A lot of useful string conversion utils are in base/string_utils.hpp +- If you don't have enough time to make it right, leave a `// TODO(DeveloperName): need to fix it` comment + +### Some useful macros: + +- `#ifdef DEBUG | RELEASE | OMIM_PRODUCTION` +- `#ifdef OMIM_OS_ANDROID | OMIM_OS_IPHONE | OMIM_OS_MAC` (and some other useful OS-related macros, see `std/target_os.hpp`) +- Use `ASSERT(expression, (out message))` and `ASSERT_XXXXXX` macros often to check code validity in DEBUG builds +- Use `CHECK(expression, (out message))` and `CHECK_XXXXXX` macros to check code validity in all builds +- Use `LOG(level, (message))` for logging, below is more detailed description for level: + * `LINFO` - always prints log message + * `LDEBUG` - logs only in DEBUG + * `LWARNING` - the same as `LINFO` but catches your attention + * `LERROR` - the same as `LWARNING`, but crashes in DEBUG and works in RELEASE + * `LCRITICAL` - the same as `LERROR` and ALWAYS crashes +- Need scope guard? Check `MY_SCOPE_GUARD(name, func)` +- Use `std::array::size()` to calculate plain C-array's size +- Declare your own exceptions with `DECLARE_EXCEPTION(name, baseException)`, where `baseException` is usually `RootException` +- Throw exceptions with `MYTHROW(exceptionName, (message))` +- A lot of useful string conversion utils are in `base/string_utils.hpp` From 96d1a98ee430acbad805513db85ce43a23cc7b2a Mon Sep 17 00:00:00 2001 From: Ilya Zverev Date: Mon, 28 Sep 2015 23:10:17 +0300 Subject: [PATCH 06/13] [docs] CLA --- docs/CLA.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 79 insertions(+), 2 deletions(-) diff --git a/docs/CLA.md b/docs/CLA.md index f54f064b0c..2f9b87923c 100644 --- a/docs/CLA.md +++ b/docs/CLA.md @@ -1,6 +1,83 @@ # Contributor License Agreement To participate in MAPS.ME development, you need to sign an agreement, which -enforces your and our rights to the code. +enforces your and our rights to the code. Please read +[this nice article](http://infrequently.org/2008/06/why-do-i-need-to-sign-this/) +for an elaboration on reasons to sign such agreements. -*todo* +NOTE: This is only a preview of the individual agreement. +Head to [maps.me/cla](http://maps.me/cla) to sign the actual form. + +## MAPS.ME Individual Contributor License Agreement + +In order to clarify the intellectual property license granted with Contributions from any person +or entity, MAPS.ME ("MAPS.ME") must have a Contributor License Agreement ("CLA") on file that has +been signed by each Contributor, indicating agreement to the license terms below. This license is +for your protection as a Contributor as well as the protection of MAPS.ME; it does not change your +rights to use your own Contributions for any other purpose. + +You accept and agree to the following terms and conditions for Your present and future Contributions +submitted to MAPS.ME. Except for the license granted herein to MAPS.ME and recipients of software +distributed by MAPS.ME, You reserve all right, title, and interest in and to Your Contributions. + +1. Definitions. + * "You" (or "Your") shall mean the copyright owner or legal entity authorized by the copyright +owner that is making this Agreement with MAPS.ME. For legal entities, the entity making a Contribution +and all other entities that control, are controlled by, or are under common control with that +entity are considered to be a single Contributor. For the purposes of this definition, "control" +means (i) the power, direct or indirect, to cause the direction or management of such entity, +whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding +shares, or (iii) beneficial ownership of such entity. + * "Contribution" shall mean any original work of authorship, including any modifications or +additions to an existing work, that is intentionally submitted by You to MAPS.ME for inclusion in, +or documentation of, any of the products owned or managed by MAPS.ME (the "Work"). For the purposes +of this definition, "submitted" means any form of electronic, verbal, or written communication sent +to MAPS.ME or its representatives, including but not limited to communication on electronic mailing +lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, +MAPS.ME for the purpose of discussing and improving the Work, but excluding communication that is +conspicuously marked or otherwise designated in writing by You as "Not a Contribution." + +2. Grant of Copyright License. Subject to the terms and conditions of this Agreement, You hereby grant +to MAPS.ME and to recipients of software distributed by MAPS.ME a perpetual, worldwide, non-exclusive, +no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, +publicly display, publicly perform, sublicense, and distribute Your Contributions and such derivative works. + +3. Grant of Patent License. Subject to the terms and conditions of this Agreement, You hereby grant +to MAPS.ME and to recipients of software distributed by MAPS.ME a perpetual, worldwide, non-exclusive, +no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, +have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license +applies only to those patent claims licensable by You that are necessarily infringed by Your +Contribution(s) alone or by combination of Your Contribution(s) with the Work to which such +Contribution(s) was submitted. If any entity institutes patent litigation against You or any other +entity (including a cross-claim or counterclaim in a lawsuit) alleging that your Contribution, or +the Work to which you have contributed, constitutes direct or contributory patent infringement, +then any patent licenses granted to that entity under this Agreement for that Contribution or Work +shall terminate as of the date such litigation is filed. + +4. You represent that you are legally entitled to grant the above license. If your employer(s) has +rights to intellectual property that you create that includes your Contributions, you represent that +you have received permission to make Contributions on behalf of that employer, that your employer +has waived such rights for your Contributions to MAPS.ME, or that your employer has executed +a separate Corporate CLA with MAPS.ME. + +5. You represent that each of Your Contributions is Your original creation (see section 7 for +submissions on behalf of others). You represent that Your Contribution submissions include complete +details of any third-party license or other restriction (including, but not limited to, related patents +and trademarks) of which you are personally aware and which are associated with any part of Your +Contributions. + +6. You are not expected to provide support for Your Contributions, except to the extent You desire +to provide support. You may provide support for free, for a fee, or not at all. Unless required +by applicable law or agreed to in writing, You provide Your Contributions on an "AS IS" BASIS, WITHOUT +WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, +any warranties or conditions of TITLE, NON- INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR +PURPOSE. + +7. Should You wish to submit work that is not Your original creation, You may submit it to MAPS.ME +separately from any Contribution, identifying the complete details of its source and of any license +or other restriction (including, but not limited to, related patents, trademarks, and license agreements) +of which you are personally aware, and conspicuously marking the work as "Submitted on behalf of +a third-party: [named here]". + +8. You agree to notify MAPS.ME of any facts or circumstances of which you become aware that would +make these representations inaccurate in any respect. From e21d04b264849c881ab1188f7dc626a4e32b9739 Mon Sep 17 00:00:00 2001 From: Ilya Zverev Date: Mon, 28 Sep 2015 23:50:15 +0300 Subject: [PATCH 07/13] [docs] Updated and documented clang format, updated install --- .clang-format | 5 ++++- docs/CPP_STYLE.md | 56 +++++++++++++++++++++++++---------------------- docs/INSTALL.md | 17 +++++++++++++- 3 files changed, 50 insertions(+), 28 deletions(-) diff --git a/.clang-format b/.clang-format index 5430c9aeaf..ee73e32f03 100644 --- a/.clang-format +++ b/.clang-format @@ -1,4 +1,4 @@ -# Configuration file for clang-format, based on docs/cpp_coding_standard.txt. +# Configuration file for clang-format, based on docs/CPP_STYLE.md. --- BasedOnStyle: Google @@ -19,3 +19,6 @@ DerivePointerAlignment: false NamespaceIndentation: None PointerAlignment: Middle Standard: Cpp11 +SpacesBeforeTrailingComments: 1 +IndentCaseLabels: false +KeepEmptyLinesAtTheStartOfBlocks: true diff --git a/docs/CPP_STYLE.md b/docs/CPP_STYLE.md index 44f3c8768c..3d30389647 100644 --- a/docs/CPP_STYLE.md +++ b/docs/CPP_STYLE.md @@ -1,7 +1,5 @@ # C++ Style Guide -**We write code without warnings!** - In general, [Google's coding standard](http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml) is used, and we strongly encourage to read it. Below are our specific (but not all!) exceptions to the Google's coding standard: @@ -24,9 +22,18 @@ Naming and formatting - Use right-to-left order for variables/params: `string const & s` (reference to the const string) - In one line `if`, `for`, `while` we do not use brackets. If one line `for` or `while` is combined with one line `if`, do use brackets for cycle. - Space after the keyword in conditions and loops. Space after `;` in `for` loop -- Space between binary operators, but can skip according to operators priority: `x = y*y + z*z` +- Space between binary operators: `x = y * y + z * z` - Space after double dash +**We write code without warnings!** + +## ClangFormat + +Most of our coding style is specified in a configuration file for [ClangFormat](http://clang.llvm.org/docs/ClangFormat.html). +To automatically format a file, install `clang-format` and run: + + clang-format -i file.cpp file.hpp other_file.cpp + ## Formatting Example/Guide/Reference ```cpp @@ -37,14 +44,8 @@ typedef double TMyTypeStartsWithCapitalTLetter; class ComplexClass { public: - Complex(double rePart, double imPart) - : m_re(rePart), m_im(imPart) - {} - - double Modulus() const - { - return sqrt(m_re * m_re + m_im * m_im); - } + Complex(double rePart, double imPart) : m_re(rePart), m_im(imPart) {} + double Modulus() const { return sqrt(m_re * m_re + m_im * m_im); } private: // We use m_ prefix for member variables @@ -67,7 +68,8 @@ namespace lower_case { template -void SomeFoo(int a, int b, TTemplateTypeStartsWithCapitalTLetter /* we avoid compilation warnings */) +void SomeFoo(int a, int b, + TTemplateTypeStartsWithCapitalTLetter /* we avoid compilation warnings */) { for (int i = 0; i < a; ++i) { @@ -80,7 +82,7 @@ void SomeFoo(int a, int b, TTemplateTypeStartsWithCapitalTLetter /* we avoid com Bar(i); Bar(b); // Commented out call - //Bar(c); + // Bar(c); } } } @@ -97,10 +99,10 @@ int Foo(int a) break; case 2: - { - Bar(2); - break; - } + { + Bar(2); + break; + } case 3: default: @@ -111,8 +113,7 @@ int Foo(int a) return 0; } - -//if, for, while formatting +// if, for, while formatting if (condition) foo(); @@ -130,7 +131,6 @@ if (condition) for (size_t i = 0; i < size; ++i) foo(i); - while (true) { if (condition) @@ -140,16 +140,20 @@ while (true) // Space after the keyword if (condition) -{} +{ +} for (size_t i = 0; i < 5; ++i) -{} +{ +} while (condition) -{} +{ +} switch (i) -{} +{ +} // Space between operators, and don't use space between unary operator and expression x = 0; @@ -158,9 +162,9 @@ x = -5; x--; x *= 5; if (x && !y) -{} +{ +} v = w * x + y / z; -v = w*x + y/z; v = w * (x + z); // space after double dash diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 4884770c10..4e79003af0 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -56,9 +56,24 @@ Then: We haven't compiled MAPS.ME on Windows in a long time, though it is possible. It is likely some make files should be updated. If you succeed, please submit a tutorial. +See also [Android compilation instructions](android_toolchain_windows.txt) (also possibly outdated). + ### Download maps -http://direct.mapswithme.com/direct/ +To browse maps in an application, you need first to download some. We maintain an archive +of all released versions of data at [direct.mapswithme.com](http://direct.mapswithme.com/direct/). +Place `.mwm` and `.mwm.routing` files to `~/Library/Application Support/MapsWithMe` for +a desktop version. Alternatively, you can put these into `omim/data`, but there +should be a soft link in a build directory: `build_omim.sh` creates it. + +For an Android application, place maps into `/MapsWithMe` directory on a device. For +iOS devices, use iTunes. + +`World.mwm` and `WorldCoasts.mwm` are low-zoom overview maps and should be placed +into a resource directory, e.g. `/Applications/MAPS.ME/Content/Resources` on Mac OS X. +Placing these into a maps directory should also work. + +For instructions on making your own maps, see [MWM.md](MWM.md). ## Maps Generator From 2406af07eaa80859f1ee233284dc54fc57d54c57 Mon Sep 17 00:00:00 2001 From: Ilya Zverev Date: Tue, 29 Sep 2015 13:13:25 +0300 Subject: [PATCH 08/13] [docs] Add copyright.html links --- NOTICE | 3 ++- README.md | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/NOTICE b/NOTICE index d82a32eba6..6e4ea3aadb 100644 --- a/NOTICE +++ b/NOTICE @@ -1,4 +1,4 @@ -Copyright 2011-2015 MAPS.ME +Copyright 2011-2015 MAPS.ME, My.com, Benstar Limited Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. @@ -15,6 +15,7 @@ limitations under the License. Most libraries in `3party` directory and in some others are made by other people and organizations and licensed in different ways: refer to their LICENCE, COPYING or NOTICE files for terms of use. +See also data/copyright.html file for a full list. All images and media content are Copyright (C) 2011-2015 MAPS.ME, published under CC-BY 4.0 license. diff --git a/README.md b/README.md index ef07618c2d..a6d4d0a5e8 100644 --- a/README.md +++ b/README.md @@ -68,4 +68,4 @@ or by mail to bugs@maps.me. This source code is Copyright (C) 2011-2015 MAPS.ME, published under Apache Public License 2.0, except third-party libraries. See [NOTICE](https://github.com/mapsme/omim/blob/master/NOTICE) -file for more information. +and [copyright.html](data/coyright.html) files for more information. From 70160d1332f9856895be909240fc57e507c54d3e Mon Sep 17 00:00:00 2001 From: Ilya Zverev Date: Tue, 29 Sep 2015 17:17:42 +0300 Subject: [PATCH 09/13] [docs] More on building, constants in CPP_STYLE --- docs/CONTRIBUTING.md | 74 +++++++++++++++++++++++++++++++++++++------- docs/CPP_STYLE.md | 48 +++++++++++++++++++--------- docs/INSTALL.md | 55 ++++++++++++++++++++++++++------ 3 files changed, 142 insertions(+), 35 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 4c859d5051..bed94e25a8 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,5 +1,15 @@ # MAPS.ME Development +## Issues + +The simplest way to contribute is to [submit an issue](https://github.com/mapsme/omim/issues). +Please give developers as much information as possible: OS and application versions, +list of actions leading to a bug, a log file that the app produces. + +When using an app on a device, use the built-in "Report a bug" option: +it creates a new e-mail with a log file attached. Your issue will be processed much +faster if you send it to bugs@maps.me. + ## Initializing the Repository The repository needs a lot of header and configuration files with private keys and such. @@ -41,23 +51,65 @@ preferences with XCode's lldb as a debugger and a clang compiler. ## Coding Style -See [CPP_STYLE.md](CPP_STYLE.md). +See [CPP_STYLE.md](CPP_STYLE.md). Use `clang-format` when in doubt. + +## Pull Requests + +All contributions to MAPS.ME source code should be submitted via github pull requests. +Each pull request is reviewed by MAPS.ME employees, to ensure consistent code style +and quality. Sometimes the review process even for smallest commits can be +very thorough. Please be patient: you may learn something about C++ or our +project in the process. + +To contribute you must sign the [license agreement](CLA.md): the same one you +sign for Google or Facebook open-source projects. ## Directories -### Sources +### Core -* **anim** - core animation controller. -* **api** - external API of the application. -* **base** - - -*todo* +* `anim` - core animation controller. +* `api` - external API of the application. +* `base` - some base things, like macros, logging, caches etc. +* `coding` - I/O classes and data processing. +* `drape` - the new graphics library core. +* `drape_frontend` - scene and resource manager for the Drape library. +* `drape_head` - an application that uses the Drape library. +* `generator` - map building tool. +* `geometry` - geometry primitives we use. +* `graphics` - the current graphics library's core +* `gui` - right, the GUI. +* `indexer` - processor for map files, classificator, styles. +* `map` - app business logic, including a scene manager. +* `platform` - platform abstraction classes: file paths, http requests, location services. +* `routing` - in-app routing engine. +* `search` - ranking and searching classes. +* `sound` - text-to-speech functions. +* `std` - standard headers wrappers, for Boost, STL, C-rt. +* `storage` - map reading function. ### Other -* **3party** - external libraries, sometimes modified. -* **android** - Android UI +Some of these contain their own README files. -*todo* +* `3party` - external libraries, sometimes modified. +* `android` - Android UI. +* `data` - data files for the application: maps, styles, country borders. +* `debian` - package sources for Debian. +* `installer` - long-abandoned installer for Windows. +* `integration_tests` - routing tests for map files. +* `iphone` - iOS UI. +* `pedestrian_routing_benchmarks` - said benchmarks. +* `qt` - desktop application. +* `qt_tstfrm` - widgets for visual testing. +* `skin_generator` - a console app for building skin files with icons and symbols. +* `stats` - Alohalytics statistics. +* `testing` - common interfaces for tests. +* `tizen` - Tizen application. +* `tools` - tools for building packages and maps, for testing etc. +* `xcode` - XCode workspace. -## Pull Requests +## Questions? + +For any questions about developing MAPS.ME and relevant services - virtually about anything related, +please write us at bugs@maps.me, we'll be happy to help. diff --git a/docs/CPP_STYLE.md b/docs/CPP_STYLE.md index 3d30389647..2b080f436b 100644 --- a/docs/CPP_STYLE.md +++ b/docs/CPP_STYLE.md @@ -4,26 +4,32 @@ In general, [Google's coding standard](http://google-styleguide.googlecode.com/s Below are our specific (but not all!) exceptions to the Google's coding standard: -- We use `.cpp` and `.hpp` files, not `.cc` and `.h` (`.c` and `.h` are used for C code), in UTF-8 encoding -- File names are lowercase with underscores, like `file_reader.cpp` +- We use `.cpp` and `.hpp` files, not `.cc` and `.h` (`.c` and `.h` are used for C code), in UTF-8 encoding. +- File names are lowercase with underscores, like `file_reader.cpp`. - We use `#pragma once` instead of the `#define` Guard in header files. -- We don't include system, std and boost headers directly, use `#include "../std/"` -- We ARE using C++ exceptions -- We are using all features of C++11 (the only known exception is thread_local which is not fully supported on all platforms) -- We don't use boost libraries which require linking (and prefer C++11 types over their boost counterparts) +- We don't include system, std and boost headers directly, use `#include "../std/"`. +- We ARE using C++ exceptions. +- We are using all features of C++11 (the only known exception is thread_local which is not fully supported on all platforms). +- We don't use boost libraries which require linking (and prefer C++11 types over their boost counterparts). Naming and formatting -- We ALWAYS use two spaces indent and don't use tabs -- We don't have hardcoded line width, but keep it reasonable to fit on the screen -- Doxygen-style comments can be used -- Underscores are allowed only in prefixes for member variables and namespace names, like `int m_countriesCount; namespace utf_parser` -- Don't specify `std::` and `boost::` prefixes (headers in std/ folder already have `using std::string`) -- Use right-to-left order for variables/params: `string const & s` (reference to the const string) +- We ALWAYS use two spaces indent and don't use tabs. +- We don't have hardcoded line width, but keep it reasonable to fit on the screen. +- Doxygen-style comments can be used. +- Underscores are allowed only in prefixes for member variables and namespace names, like `int m_countriesCount; namespace utf_parser`. +- Don't specify `std::` and `boost::` prefixes (headers in std/ folder already have `using std::string`). +- Use right-to-left order for variables/params: `string const & s` (reference to the const string). - In one line `if`, `for`, `while` we do not use brackets. If one line `for` or `while` is combined with one line `if`, do use brackets for cycle. -- Space after the keyword in conditions and loops. Space after `;` in `for` loop -- Space between binary operators: `x = y * y + z * z` -- Space after double dash +- Space after the keyword in conditions and loops. Space after `;` in `for` loop. +- Space between binary operators: `x = y * y + z * z`. +- Space after double dash. +- Compile-time constants must be named in camelCase, starting with a lower-case `k`, e.g. `kCompileTimeConstant`. +- Values of enum classes must be named in CamelCase, e.g. `enum class Color { Red, Green, LightBlue };`. +- Macroses and C-style enums must be named in UPPER_CASE, and enum values must be prefixed with a capitalized enum name. + + Note that macroses complicate debugging, and old-style enums have dangerous implicit conversions to integers, and tend to clutter + containing namespaces. Avoid them when possible - use `const` or `constexpr` instead of macroses, and enum classes instead of enums. **We write code without warnings!** @@ -37,8 +43,20 @@ To automatically format a file, install `clang-format` and run: ## Formatting Example/Guide/Reference ```cpp +#pragma once + #include "../std/math.hpp" +const uint16_t kBufferSize = 255; + +// C-style enum. Do not use these. +enum Type +{ + TYPE_INTEGER, + TYPE_FLOAT, + TYPE_STRING +}; + typedef double TMyTypeStartsWithCapitalTLetter; class ComplexClass diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 4e79003af0..1bf504d991 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -5,7 +5,7 @@ First, do not forget to initialize a cloned repository, see ## Desktop -You would need Boost and Qt 5. With that, just run `omim/tools/unix/build_omim.sh`. +You would need Clang, Boost and Qt 5. With that, just run `omim/tools/unix/build_omim.sh`. It will build both debug and release versions to `omim/../omim-build-`, as well as OSRM backend for generating maps. Command-line switches are: @@ -14,8 +14,9 @@ well as OSRM backend for generating maps. Command-line switches are: * `-o` to build OSRM backend * `-c` to delete target directories before building -To build a generator tool only, set `CONFIG=gtool` flag. To skip building tests, -use `CONFIG=no-tests`. +To build a generator tool only, set `CONFIG=gtool` variable. To skip building tests, +use `CONFIG=no-tests`. If you have Qt installed in an unusual directory, use +`QMAKE` variable. When using a lot of maps, increase open files limit, which is only 256 on Mac OS X. Use `ulimit -n 2000`, put it into `~/.bash_profile` to apply it to all new sessions. @@ -24,14 +25,31 @@ and run echo 'ulimit -n 2048' | sudo tee -a /etc/profile +### Building Manually + +The `build_omim.sh` script basically runs these commands: + + qmake omim.pro -spec linux-clang CONFIG+=debug + make -j + +It will compile binaries to the `out` subdirectory of the current directory. +You might need to export `BOOST_INCLUDEDIR` variable with a path to Boost's +`include` directory. + +To build the OSRM backend, create `omim/3party/osrm/osrm-backend/build` +directory, and from within it, run: + + cmake -DBOOST_ROOT= .. + make + ### Ubuntu 14.04 -Install Qt 5.4: +Install Qt 5.5: - sudo add-apt-repository ppa:beineri/opt-qt542-trusty + sudo add-apt-repository ppa:beineri/opt-qt55-trusty sudo apt-get update - sudo apt-get install qt54base - source /opt/qt54/bin/qt54-env.sh + sudo apt-get install qt55base + source /opt/qt55/bin/qt55-env.sh To run OSRM binaries, you'll need: @@ -41,7 +59,7 @@ Do a git clone: git clone git@github.com:mapsme/omim.git cd omim - ./configure.sh + echo | ./configure.sh Then: @@ -77,7 +95,24 @@ For instructions on making your own maps, see [MWM.md](MWM.md). ## Maps Generator -### OSRM Backend +The generator tool is build together with the desktop app, but you can choose to skip +other modules. Use this line: + + CONFIG=gtool omim/tools/unix/build_omim.sh -ro + +It is the preferable way to build a generator tool, for it can also build an OSRM +backend (`-o` option). + +Dependencies for generator tool and OSRM backend: + +* boost-iostreams +* glu1-mesa +* tbb +* luabind +* stxxl +* osmpbf +* protobuf +* lua ## Designer Tool @@ -135,3 +170,5 @@ to SDK and NDK. Or specify these in command line: receive a log file. ## iOS + +*todo* From 5f901943cbd69f4f08b5c06437e297996fc9fa0c Mon Sep 17 00:00:00 2001 From: Ilya Zverev Date: Tue, 29 Sep 2015 19:30:37 +0300 Subject: [PATCH 10/13] [docs] Updated license and texts --- LICENSE | 27 --------------------------- NOTICE | 4 ++-- README.md | 14 ++++++-------- docs/CLA.md | 4 ++-- docs/CONTRIBUTING.md | 9 ++++----- docs/CPP_STYLE.md | 12 ++++++------ 6 files changed, 20 insertions(+), 50 deletions(-) diff --git a/LICENSE b/LICENSE index d645695673..67db858821 100644 --- a/LICENSE +++ b/LICENSE @@ -173,30 +173,3 @@ defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. diff --git a/NOTICE b/NOTICE index 6e4ea3aadb..0b7b7658f0 100644 --- a/NOTICE +++ b/NOTICE @@ -1,4 +1,4 @@ -Copyright 2011-2015 MAPS.ME, My.com, Benstar Limited +Copyright 2011-2015 My.com B.V. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. @@ -17,5 +17,5 @@ by other people and organizations and licensed in different ways: refer to their LICENCE, COPYING or NOTICE files for terms of use. See also data/copyright.html file for a full list. -All images and media content are Copyright (C) 2011-2015 MAPS.ME, +All images and media content are Copyright (C) 2011-2015 My.com B.V., published under CC-BY 4.0 license. diff --git a/README.md b/README.md index a6d4d0a5e8..32f4d32f20 100644 --- a/README.md +++ b/README.md @@ -45,20 +45,18 @@ format description, instructions on building a style and some links. ## Development -You would need Qt 5 for development, most other libraries are included into the -repository, see `3party` directory. The team uses mostly XCode and Qt Creator, +You would need Boost and Qt 5 for development, most other libraries are included into the +repository: see `3party` directory. The team uses mostly XCode and Qt Creator, though these are not mandatory. We have an established [coding style](https://github.com/mapsme/omim/blob/master/docs/CPP_STYLE.md). -Our pull request review process may be intimidating, but it ensures a consistent -code quality. - -All contributors must sign a [Contributor Agreement](https://github.com/mapsme/omim/blob/master/docs/CLA.md), -so both ours and theirs rights are protected. See [CONTRIBUTING.md](https://github.com/mapsme/omim/blob/master/docs/CONTRIBUTING.md) for the repository initialization process, the description of all the directories of this repository and other development-related information. +All contributors must sign a [Contributor Agreement](https://github.com/mapsme/omim/blob/master/docs/CLA.md), +so both our and their rights are protected. + ## Feedback Please report bugs and suggestions to [the issue tracker](https://github.com/mapsme/omim/issues), @@ -66,6 +64,6 @@ or by mail to bugs@maps.me. ## Authors and License -This source code is Copyright (C) 2011-2015 MAPS.ME, published under Apache Public License 2.0, +This source code is Copyright (C) 2011-2015 My.com B.V., published under Apache Public License 2.0, except third-party libraries. See [NOTICE](https://github.com/mapsme/omim/blob/master/NOTICE) and [copyright.html](data/coyright.html) files for more information. diff --git a/docs/CLA.md b/docs/CLA.md index 2f9b87923c..5136bb5f1c 100644 --- a/docs/CLA.md +++ b/docs/CLA.md @@ -1,7 +1,7 @@ # Contributor License Agreement -To participate in MAPS.ME development, you need to sign an agreement, which -enforces your and our rights to the code. Please read +To participate in MAPS.ME development you need to sign an agreement. +It protects your and our rights to the code. Please read [this nice article](http://infrequently.org/2008/06/why-do-i-need-to-sign-this/) for an elaboration on reasons to sign such agreements. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index bed94e25a8..af15445571 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -4,9 +4,9 @@ The simplest way to contribute is to [submit an issue](https://github.com/mapsme/omim/issues). Please give developers as much information as possible: OS and application versions, -list of actions leading to a bug, a log file that the app produces. +list of actions leading to a bug, a log file produced by the app. -When using an app on a device, use the built-in "Report a bug" option: +When using the MAPS.ME app on a device, use the built-in "Report a bug" option: it creates a new e-mail with a log file attached. Your issue will be processed much faster if you send it to bugs@maps.me. @@ -58,8 +58,7 @@ See [CPP_STYLE.md](CPP_STYLE.md). Use `clang-format` when in doubt. All contributions to MAPS.ME source code should be submitted via github pull requests. Each pull request is reviewed by MAPS.ME employees, to ensure consistent code style and quality. Sometimes the review process even for smallest commits can be -very thorough. Please be patient: you may learn something about C++ or our -project in the process. +very thorough. To contribute you must sign the [license agreement](CLA.md): the same one you sign for Google or Facebook open-source projects. @@ -112,4 +111,4 @@ Some of these contain their own README files. ## Questions? For any questions about developing MAPS.ME and relevant services - virtually about anything related, -please write us at bugs@maps.me, we'll be happy to help. +please write to us at bugs@maps.me, we'll be happy to help. diff --git a/docs/CPP_STYLE.md b/docs/CPP_STYLE.md index 2b080f436b..08c515b433 100644 --- a/docs/CPP_STYLE.md +++ b/docs/CPP_STYLE.md @@ -7,7 +7,7 @@ Below are our specific (but not all!) exceptions to the Google's coding standard - We use `.cpp` and `.hpp` files, not `.cc` and `.h` (`.c` and `.h` are used for C code), in UTF-8 encoding. - File names are lowercase with underscores, like `file_reader.cpp`. - We use `#pragma once` instead of the `#define` Guard in header files. -- We don't include system, std and boost headers directly, use `#include "../std/"`. +- We don't include system, std and boost headers directly, use `#include "std/"`. - We ARE using C++ exceptions. - We are using all features of C++11 (the only known exception is thread_local which is not fully supported on all platforms). - We don't use boost libraries which require linking (and prefer C++11 types over their boost counterparts). @@ -26,10 +26,10 @@ Naming and formatting - Space after double dash. - Compile-time constants must be named in camelCase, starting with a lower-case `k`, e.g. `kCompileTimeConstant`. - Values of enum classes must be named in CamelCase, e.g. `enum class Color { Red, Green, LightBlue };`. -- Macroses and C-style enums must be named in UPPER_CASE, and enum values must be prefixed with a capitalized enum name. +- Macros and C-style enums must be named in UPPER_CASE, and enum values must be prefixed with a capitalized enum name. - Note that macroses complicate debugging, and old-style enums have dangerous implicit conversions to integers, and tend to clutter - containing namespaces. Avoid them when possible - use `const` or `constexpr` instead of macroses, and enum classes instead of enums. + Note that macros complicate debugging, and old-style enums have dangerous implicit conversions to integers, and tend to clutter + containing namespaces. Avoid them when possible - use `const` or `constexpr` instead of macros, and enum classes instead of enums. **We write code without warnings!** @@ -45,9 +45,9 @@ To automatically format a file, install `clang-format` and run: ```cpp #pragma once -#include "../std/math.hpp" +#include "std/math.hpp" -const uint16_t kBufferSize = 255; +uint16_t const kBufferSize = 255; // C-style enum. Do not use these. enum Type From 7c9b164bccf4bd01236a68e3ba0f53ad6dbfd421 Mon Sep 17 00:00:00 2001 From: Ilya Zverev Date: Tue, 29 Sep 2015 19:55:14 +0300 Subject: [PATCH 11/13] [docs] iOS simulator running --- docs/INSTALL.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 1bf504d991..7b8ce0f9be 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -171,4 +171,11 @@ to SDK and NDK. Or specify these in command line: ## iOS -*todo* +For XCode configuration instructions, see [CONTRIBUTING.md](CONTRIBUTING.md). + +* Open `omim/iphone/Maps/Maps.xcodeproj` in XCode. +* Open "Product → Scheme → Edit Scheme", then "Info" and change build configuration to Simulator. +* Run the project (Product → Run). + +If a script has trouble finding your Qt 5 installation, edit `omim/autobuild/detect_qmake.sh`, +adding a path to `qmake` there. From d5764aa625e13129ca83ff055079473fd8cf1951 Mon Sep 17 00:00:00 2001 From: Ilya Zverev Date: Tue, 29 Sep 2015 20:01:40 +0300 Subject: [PATCH 12/13] [docs] Rewording of some text in readme --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 32f4d32f20..ee3e3554a2 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ # MAPS.ME -http://maps.me - -This is an application for [Android](https://play.google.com/store/apps/details?id=com.mapswithme.maps.pro) -and [iOS](https://itunes.apple.com/app/id510623322) devices for offline maps built from OpenStreetMap data. +[MAPS.ME](http://maps.me) is an open source cross-platform offline maps application, +built on top of crowd-sourced OpenStreetMap data. It was publicly released +for [iOS](https://itunes.apple.com/app/id510623322) and +[Android](https://play.google.com/store/apps/details?id=com.mapswithme.maps.pro). ## Submodules @@ -45,7 +45,7 @@ format description, instructions on building a style and some links. ## Development -You would need Boost and Qt 5 for development, most other libraries are included into the +You would need Qt 5 for development, most other libraries are included into the repository: see `3party` directory. The team uses mostly XCode and Qt Creator, though these are not mandatory. We have an established [coding style](https://github.com/mapsme/omim/blob/master/docs/CPP_STYLE.md). From 292c4e57797a6bb248a40752281747edb47660cf Mon Sep 17 00:00:00 2001 From: Ilya Zverev Date: Tue, 29 Sep 2015 20:28:05 +0300 Subject: [PATCH 13/13] [docs] Fixed link in readme and replace maps.me with my.com in CLA --- README.md | 2 +- docs/CLA.md | 32 ++++++++++++++++---------------- 2 files changed, 17 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index ee3e3554a2..92c116f27f 100644 --- a/README.md +++ b/README.md @@ -66,4 +66,4 @@ or by mail to bugs@maps.me. This source code is Copyright (C) 2011-2015 My.com B.V., published under Apache Public License 2.0, except third-party libraries. See [NOTICE](https://github.com/mapsme/omim/blob/master/NOTICE) -and [copyright.html](data/coyright.html) files for more information. +and [copyright.html](https://github.com/mapsme/omim/blob/master/data/copyright.html) files for more information. diff --git a/docs/CLA.md b/docs/CLA.md index 5136bb5f1c..57d2859cfb 100644 --- a/docs/CLA.md +++ b/docs/CLA.md @@ -8,42 +8,42 @@ for an elaboration on reasons to sign such agreements. NOTE: This is only a preview of the individual agreement. Head to [maps.me/cla](http://maps.me/cla) to sign the actual form. -## MAPS.ME Individual Contributor License Agreement +## My.com Individual Contributor License Agreement In order to clarify the intellectual property license granted with Contributions from any person -or entity, MAPS.ME ("MAPS.ME") must have a Contributor License Agreement ("CLA") on file that has +or entity, My.com B.V. ("My.com") must have a Contributor License Agreement ("CLA") on file that has been signed by each Contributor, indicating agreement to the license terms below. This license is -for your protection as a Contributor as well as the protection of MAPS.ME; it does not change your +for your protection as a Contributor as well as the protection of My.com; it does not change your rights to use your own Contributions for any other purpose. You accept and agree to the following terms and conditions for Your present and future Contributions -submitted to MAPS.ME. Except for the license granted herein to MAPS.ME and recipients of software -distributed by MAPS.ME, You reserve all right, title, and interest in and to Your Contributions. +submitted to My.com. Except for the license granted herein to My.com and recipients of software +distributed by My.com, You reserve all right, title, and interest in and to Your Contributions. 1. Definitions. * "You" (or "Your") shall mean the copyright owner or legal entity authorized by the copyright -owner that is making this Agreement with MAPS.ME. For legal entities, the entity making a Contribution +owner that is making this Agreement with My.com. For legal entities, the entity making a Contribution and all other entities that control, are controlled by, or are under common control with that entity are considered to be a single Contributor. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. * "Contribution" shall mean any original work of authorship, including any modifications or -additions to an existing work, that is intentionally submitted by You to MAPS.ME for inclusion in, -or documentation of, any of the products owned or managed by MAPS.ME (the "Work"). For the purposes +additions to an existing work, that is intentionally submitted by You to My.com for inclusion in, +or documentation of, any of the products owned or managed by My.com (the "Work"). For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent -to MAPS.ME or its representatives, including but not limited to communication on electronic mailing +to My.com or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, -MAPS.ME for the purpose of discussing and improving the Work, but excluding communication that is +My.com for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by You as "Not a Contribution." 2. Grant of Copyright License. Subject to the terms and conditions of this Agreement, You hereby grant -to MAPS.ME and to recipients of software distributed by MAPS.ME a perpetual, worldwide, non-exclusive, +to My.com and to recipients of software distributed by My.com a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute Your Contributions and such derivative works. 3. Grant of Patent License. Subject to the terms and conditions of this Agreement, You hereby grant -to MAPS.ME and to recipients of software distributed by MAPS.ME a perpetual, worldwide, non-exclusive, +to My.com and to recipients of software distributed by My.com a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by You that are necessarily infringed by Your @@ -57,8 +57,8 @@ shall terminate as of the date such litigation is filed. 4. You represent that you are legally entitled to grant the above license. If your employer(s) has rights to intellectual property that you create that includes your Contributions, you represent that you have received permission to make Contributions on behalf of that employer, that your employer -has waived such rights for your Contributions to MAPS.ME, or that your employer has executed -a separate Corporate CLA with MAPS.ME. +has waived such rights for your Contributions to My.com, or that your employer has executed +a separate Corporate CLA with My.com. 5. You represent that each of Your Contributions is Your original creation (see section 7 for submissions on behalf of others). You represent that Your Contribution submissions include complete @@ -73,11 +73,11 @@ WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, with any warranties or conditions of TITLE, NON- INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. -7. Should You wish to submit work that is not Your original creation, You may submit it to MAPS.ME +7. Should You wish to submit work that is not Your original creation, You may submit it to My.com separately from any Contribution, identifying the complete details of its source and of any license or other restriction (including, but not limited to, related patents, trademarks, and license agreements) of which you are personally aware, and conspicuously marking the work as "Submitted on behalf of a third-party: [named here]". -8. You agree to notify MAPS.ME of any facts or circumstances of which you become aware that would +8. You agree to notify My.com of any facts or circumstances of which you become aware that would make these representations inaccurate in any respect.