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/LICENSE b/LICENSE new file mode 100644 index 0000000000..67db858821 --- /dev/null +++ b/LICENSE @@ -0,0 +1,175 @@ + + 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. diff --git a/NOTICE b/NOTICE new file mode 100644 index 0000000000..0b7b7658f0 --- /dev/null +++ b/NOTICE @@ -0,0 +1,21 @@ +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. +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. +See also data/copyright.html file for a full list. + +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 new file mode 100644 index 0000000000..92c116f27f --- /dev/null +++ b/README.md @@ -0,0 +1,69 @@ +# MAPS.ME + +[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 + +This repository contains submodules. Clone it with `git clone --recursive`. If you forgot, +run `git submodule update --init --recursive`. + +## Compilation + +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). + +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. 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). + +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), +or by mail to bugs@maps.me. + +## Authors and License + +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](https://github.com/mapsme/omim/blob/master/data/copyright.html) files for more information. diff --git a/docs/CLA.md b/docs/CLA.md new file mode 100644 index 0000000000..57d2859cfb --- /dev/null +++ b/docs/CLA.md @@ -0,0 +1,83 @@ +# Contributor License Agreement + +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. + +NOTE: This is only a preview of the individual agreement. +Head to [maps.me/cla](http://maps.me/cla) to sign the actual form. + +## My.com Individual Contributor License Agreement + +In order to clarify the intellectual property license granted with Contributions from any person +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 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 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 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 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 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, +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 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 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 +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 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 +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 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 My.com of any facts or circumstances of which you become aware that would +make these representations inaccurate in any respect. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000000..af15445571 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,114 @@ +# 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 produced by the app. + +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. + +## 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 + +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. + +To contribute you must sign the [license agreement](CLA.md): the same one you +sign for Google or Facebook open-source projects. + +## Directories + +### Core + +* `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 + +Some of these contain their own README files. + +* `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. + +## Questions? + +For any questions about developing MAPS.ME and relevant services - virtually about anything related, +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 new file mode 100644 index 0000000000..08c515b433 --- /dev/null +++ b/docs/CPP_STYLE.md @@ -0,0 +1,220 @@ +# 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. + +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 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). +- 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. +- 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 };`. +- Macros and C-style enums must be named in UPPER_CASE, and enum values must be prefixed with a capitalized enum name. + + 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!** + +## 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 +#pragma once + +#include "std/math.hpp" + +uint16_t const kBufferSize = 255; + +// C-style enum. Do not use these. +enum Type +{ + TYPE_INTEGER, + TYPE_FLOAT, + TYPE_STRING +}; + +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); } + +private: + // We use m_ prefix for member variables + double m_re; + double m_im; +}; + +namespace +{ + +void CamelCaseFunctionName(int lowerCamelCaseVar) +{ + static int counter = 0; + counter += lowerCamelCaseVar; +} + +} // namespace + +namespace lower_case +{ + +template +void SomeFoo(int a, int b, + TTemplateTypeStartsWithCapitalTLetter /* we avoid compilation warnings */) +{ + for (int i = 0; i < a; ++i) + { + // IMPORTANT! We DON'T use one-liners for if statements for easier debugging. + // The following syntax is invalid: if (i < b) Bar(i); + if (i < b) + Bar(i); + else + { + Bar(i); + Bar(b); + // Commented out call + // Bar(c); + } + } +} + +} // namespace lower_case + +// Switch formatting +int Foo(int a) +{ + switch (a) + { + case 1: + Bar(1); + break; + + case 2: + { + Bar(2); + break; + } + + case 3: + default: + Bar(3); + break; + } + + return 0; +} + +// if, for, while formatting + +if (condition) + foo(); +else + bar(); + +if (condition) +{ + if (condition) + foo(); + else + bar(); +} + +for (size_t i = 0; i < size; ++i) + foo(i); + +while (true) +{ + if (condition) + break; +} + +// 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; +x = -5; +++x; +x--; +x *= 5; +if (x && !y) +{ +} +v = w * x + y / z; +v = w * (x + z); + +// space after double dash +``` + +## 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 +- Your code should compile well with gcc 4.8+ and clang 3.5+ +- Try to avoid using any new 3party library if it is not fully tested and supported on all our platforms +- Cover your code with unit tests! See examples for existing libraries +- Check Base and Coding libraries for most of the basic functions +- 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 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` diff --git a/docs/INSTALL.md b/docs/INSTALL.md new file mode 100644 index 0000000000..7b8ce0f9be --- /dev/null +++ b/docs/INSTALL.md @@ -0,0 +1,181 @@ +# Building MAPS.ME + +First, do not forget to initialize a cloned repository, see +[CONTRIBUTING.md](CONTRIBUTING.md). + +## Desktop + +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: + +* `-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` 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. +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 + +### 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.5: + + sudo add-apt-repository ppa:beineri/opt-qt55-trusty + sudo apt-get update + sudo apt-get install qt55base + source /opt/qt55/bin/qt55-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 + echo | ./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. + +See also [Android compilation instructions](android_toolchain_windows.txt) (also possibly outdated). + +### Download maps + +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 + +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 + +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 + +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. 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 diff --git a/docs/cpp_coding_standard.txt b/docs/cpp_coding_standard.txt deleted file mode 100644 index fa7bf65a71..0000000000 --- a/docs/cpp_coding_standard.txt +++ /dev/null @@ -1,192 +0,0 @@ -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 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) -- 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 *********** -#include "../std/math.hpp" - -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); - } - -private: - // We use m_ prefix for member variables - double m_re; - double m_im; -}; - -namespace -{ - -void CamelCaseFunctionName(int lowerCamelCaseVar) -{ - static int counter = 0; - counter += lowerCamelCaseVar; -} - -} // namespace - -namespace lower_case -{ - -template -void SomeFoo(int a, int b, TTemplateTypeStartsWithCapitalTLetter /* we avoid compilation warnings */) -{ - for (int i = 0; i < a; ++i) - { - // IMPORTANT! We DON'T use one-liners for if statements for easier debugging. - // The following syntax is invalid: if (i < b) Bar(i); - if (i < b) - Bar(i); - else - { - Bar(i); - Bar(b); - // Commented out call - //Bar(c); - } - } -} - -} // namespace lower_case - -// Switch formatting -int Foo(int a) -{ - switch (a) - { - case 1: - Bar(1); - break; - - case 2: - { - Bar(2); - break; - } - - case 3: - default: - Bar(3); - break; - } - - return 0; -} - - -//if, for, while formatting - -if (condition) - foo(); -else - bar(); - -if (condition) -{ - if (condition) - foo(); - else - bar(); -} - -for (size_t i = 0; i < size; ++i) - foo(i); - - -while (true) -{ - if (condition) - break; -} - -// 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; -x = -5; -++x; -x--; -x *= 5; -if (x && !y) -{} -v = w * x + y / z; -v = w*x + y/z; -v = w * (x + z); - -// space after double dash - - -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 -- Your code should compile well with gcc 4.8+ and clang 3.5+ -- Try to avoid using any new 3party library if it is not fully tested and supported on all our platforms -- Cover your code with unit tests! See examples for existing libraries -- Check Base and Coding libraries for most of the basic functions -- 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