c:geo
c:geo is an open-source, full-featured, always ready-to-go client for geocaching.com (unofficial). It also offers basic support for other geocaching platforms. It does not require a web browser or exports - just download and start right away.
Want to contribute?
Perfect! Please tell us in the issue tracker before hacking on your great new feature. It would be bad for you to have implemented something great but we can't include it because it doesn't fit the existing architecture and code.
Starting points for contribution
You can also take a look at the project page of our repository. For example, we have a collection of urgent issues and a list of beginner topics. They collect issues that might be suitable for your first contribution.
Project status
Get the source
Fork the project source code, make changes to your clone, and create a pull request afterwards.
Branches
masteris for the development of new features. Nightly builds are created from this branch.releaseis for all bug fixes of already existing features. So if a bug is reported in a released version, it should be fixed on this branch (and merged tomasterafterwards).
Note: Regular merging of release to master (after changes have been done on release) is highly recommended to avoid unnecessary merge conflicts later on.
A more complex bugfix can first be tested against the master branch and integrated in the nightly builds while kept compatible with the release branch for a later integration. Such a procedure is described in the wiki.
Setting up an IDE
The standard IDE for Android projects is Android Studio, which is based on IntelliJ IDEA. We use it for the development of c:geo.
Details for setting up the IDE are described in the wiki (https://github.com/cgeo/cgeo/wiki/IDE).
Build
Prerequisites
- Android SDK (latest version) including Google APIs (at least) V26, Google repository, and Android support repository. (File => Settings, Appearance & Behaviour => System Settings => Android SDK, Check "Show Package Details" on "SDK Platforms" tab and check subpackages as needed.)
- If you use Microsoft Windows, Google USB Driver to install the application on the smartphone.
- You need to provide several API keys for compiling the app (see following sections for details).
API keys
For the full usability of c:geo you need some API keys for Google Maps and the opencaching sites. You can leave all entries in the configuration empty, but Google Maps and the Opencaching sites will not work.
For using the Google Maps function, it is necessary to have a Google Maps API v2 key. For this, follow
The key itself is free and you don't have to enter any credit card info (although the web form seems to force you to).
To be able to use Google Maps you need to use a Google API-enabled image, so make sure to select the right image for your emulator/device, otherwise Google Maps won't be offered as a map provider in c:geo.
Request your personal API key for the various OpenCaching sites we support. If you leave these blank, those networks will remain disabled.
- opencaching.de OKAPI signup
- opencaching.pl OKAPI signup
- opencaching.ro OKAPI signup
- opencaching.nl OKAPI signup
- opencaching.us OKAPI signup
- opencache.uk OKAPI signup
To obtain an API key for geocaching.su you need to request access from administration. Keys are generated manually on request.
API keys installation
For c:geo we have a semi-automatic configuration:
- Copy
./templates/private.propertiesto./ - Edit
private.propertieswith your keys - The
./main/res/values/keys.xmlis created on the gradle build and filled with the data fromprivate.properties
The third point works only if the file keys.xml does not exist. When changing your API keys, you have to delete the keys.xml file.
If you want to fill the keys.xml by hand, copy ./main/templates/keys.xml to ./main/res/values/, then edit the copied keys.xml. For each key, replace the value starting with @ and ending with @ (inclusive) with the key. If a key is missing, remove the value and the leading and trailing @.
Building with gradle
Run gradlew from the root directory of the git repository. That will install the necessary build framework and display how to build c:geo. gradlew assembleBasicDebug might be a good start. Alternatively you can use "make" in Android Studio ("Build" => "Make Project").
To be able to create an installable Android package (APK), you need to create a signing key first. In Android Studio go to "Build" => "Generate Signed Bundle & APK", select "APK", and follow the instructions. You will create a key storage and a project-specific key. Enter path and access information to those in file cgeo/private.properties.
Testing
The Test classes can be found in the project test. Test classes should be located in the same package as the class under test. Every class can be run with Run '<class name>' or debugged with Debug '<class name>') as an Android JUnit Test. To run all tests use the same Run 'Tests in <package name>' menu item from the context menu of a package in the test project.
For tests to run successfully you need to configure c:geo on the emulator that runs the test with a valid geocaching.com account. In order for all tests to be successful the account needs to be a premium member.
Tests may also be launched from the command line. Use gradlew assembleBasicDebug from the root directory of the git repository.
Deploying the app locally for testing purposes
Android Studio needs to be configured for which device(s) c:geo will be deployed to. Use "run" => "run" (2nd entry with this heading). You can create several profiles for a physical device attached via USB, as well as virtual devices that are run in an emulator. (If the emulator is not installed yet, do so via File => Settings, Appearance & Behaviour => System Settings => Android SDK, tab "SDK Tools", check "Android Emulator", and apply.)
License
c:geo is distributed under the Apache License, Version 2.0.
This product includes software developed by the c:geo team and contributors as well as parts developed elsewhere. See the references in main/res/values/strings_not_translatable.xml for details (or "about: contributors" page in the app).
Contact
- Website: https://www.cgeo.org/
- Support: [email protected]
- Twitter: https://twitter.com/android_gc
- Facebook: https://www.facebook.com/android.geocaching
- Google Play: https://play.google.com/store/apps/details?id=cgeo.geocaching
- Live status: https://status.cgeo.org/
77 Dec 9, 2022
1.3k Dec 27, 2022
1.8k Nov 10, 2022
0 Nov 29, 2021
5.7k Dec 22, 2022
117 Dec 23, 2022
167 Dec 19, 2022
21 Dec 12, 2022
362 Jan 2, 2023
13 Feb 21, 2022
341 Jan 1, 2023
791 Dec 30, 2022
3 Dec 4, 2021
3 Aug 7, 2022
107 Dec 31, 2022
2.6k Dec 25, 2022
315 Nov 14, 2022
334 Nov 29, 2022