mnalis/organicmaps
1
Fork 0
forked from organicmaps/organicmaps
Code Pull requests Activity

Merge pull request #64 from Zverik/readme

Browse source 
Base README files
This commit is contained in:
Alex Zolotarev 2015-09-29 10:31:26 -07:00
commit b6a68848c5
11 changed files with 893 additions and 193 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
.clang-format
View file

@ -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

175
LICENSE Normal file
View file

@ -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.

21
NOTICE Normal file
View file

@ -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.

69
README.md Normal file
View file

@ -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.

83
docs/CLA.md Normal file
View file

@ -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.

114
docs/CONTRIBUTING.md Normal file
View file

@ -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.

220
docs/CPP_STYLE.md Normal file
View file

@ -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/<wrapper.hpp>"`.
- 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 <class TTemplateTypeStartsWithCapitalTLetter>
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`

181
docs/INSTALL.md Normal file
View file

@ -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-<target>`, 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 <number_of_processes>
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=<where_is_your_Boost> ..
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.

11
docs/MWM.md Normal file
View file

@ -0,0 +1,11 @@
# MWM Files
## Building
### Single region
### Part of a planet
### Testing
## Format

15
docs/STYLES.md Normal file
View file

@ -0,0 +1,15 @@
# Styling MAPS.ME
## MapCSS Source
### Symbols
## Compiling Styles
## Designer Tool
## UI Resources
### Android
### iOS

192
docs/cpp_coding_standard.txt
View file

@ -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/<wrapper.hpp>"
- 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 <class TTemplateTypeStartsWithCapitalTLetter>
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