Android Gears is a new dependency management system built on open source technology through Github. Android Gears provides a beautiful user interface right in Android Studio for discovering, using and updating Android libraries. It is fully integrated with the Gradle build processes of Android Studio and IntelliJ. In addition to providing a robust search interface for library discovery, Android Gears greatly reduces the effort it takes to share your library with others. Listing your library with Android Gears is just a pull request away.
An example of searching for, downloading and using an Android library in your project in under 15 seconds.
2A. Install the Android Gears IntelliJ plugin by going to Android Studio > Preferences> Plugins and searching "Android Gears"
or
2B. Download latest Android Gears release
Mac (OSX 10.9+ tested)
Windows (Win8 tested) & Linux (Ubuntu 14.04 tested)
( Android Gears also tested in Community version of Intellij )
(Note For updating plugin) When updating first Navigate back to Plugins in IDE then uninstall plugin first then go through installation process again to get the plugin to update correctly.
Finally, to access the Android Gears menu, navigate to Tools -> Android Gears (Win&Linux-Crtl+Alt+Shift+G , M)(OSX - Command+Alt+Shift+G,M)
The Android Gears plugin for Android Studio and IntelliJ is the engine that makes Android Gears work. It coordinates with the Specs Repository and your project to ensure that managing libraries is as painless as possible. This section will cover the basics of the plugin including how to install and uninstall Gears, as well as finer points like auto-syncing Gears across teams.
To manage the Android Gears for a given project, select Tools -> Android Gears -> Manage Android Gears.
Gear Specs is a text file that holds information about an Android library listed in Android Gears. The Android Gears plugin for Android Studio comes with a GUI for creating a Gear Spec that may be pulled into the Specs Repository. Use this tool to create a listing for your library. For more information about the process, see Adding Your Library to Android Gears.
When using GUI First go to Tools > Android Gears > Create GearSpec
Then fill out form as best you can and we will tell you if you have done it correctly.
Things to take into consideration.
The plugin also has a built-in linting tool for making sure your .gearspec file is valid before issuing a pull request to the Specs Repository. This tool will tell you if there is anything wrong. This same linting tool is used by the "Create Gear Spec" mechanism.
Before getting started with Android Gears, you may find it helpful to gain a better understanding of how things work "under the hood". This section will detail some core terminology that helps make sense of the Gears system.
A Gear is simply another name for an Android or Java library. Gears come in two well-known flavors, JARs and modules. Both are downloaded, installed and maintained in the same way by the Android Gears plugin. Gears will show up in the root of your project folder with JARs and Modules stored in separate folders for easy access.
Both will be available to view in your project immediately after installing them and synchronizing your project.
The Specs Repository is a Github repository owned by the Android Gears organization. It houses all the metadata on Gears that are available for download through the Android Gears plugin. The repository is laid out with the following rules:
.gearspec with the name of the file being the library name (i.e. "Colours.gearspec")Below is an annotated screenshot of a cloned copy of the specs repository:
A .gearspec file is a text file containing a JSON packet with information about a library and its version. These files are the fundamental unit of the repository and let the Android Gears plugin know about a specific version number. Information includes the library name, version number, location for download, release notes for the specific version and a host of other data. The contents of a sample .gearspec file can be found below:
{
"name": "Colours",
"summary": "A beautiful set of predefined colors and a set of color methods to make your Android development life easier.",
"realease_notes":"The initial release of Colours for Android",
"version": "1.0.0",
"type": "module",
"copyright": "Matthew York 2014",
"homepage": "https://github.com/MatthewYork/Colours",
"license": "MIT",
"authors": [
{
"name": "Matthew York",
"email": "[email protected]"
}
],
"minimum_api": 9,
"source": {
"url": "https://github.com/MatthewYork/Colours.git",
"tag": "v1.0.0",
"source_files": "ColoursLibrary"
},
"dependencies": null,
"tags": [
"color",
"colour",
"utility",
"hsb",
"rgb",
"scheme"
]
}
You can use your favorite text editor like Sublime Text or Atom to create a .gearspec, or you can use the GUI based .gearspec creator available as part of the Android Gears plugin.
You may ask the question, "How does the Android Gears plugin communicate with the Specs Repository?" Whenever Android Gears opens for the first time, it clones down a copy of the Specs Repository (typically a very small download) to your user directory. Once the initial clone is complete, any updates to the specs repository on Github are automatically pulled down whenever you open your IDE giving you access to the latest available Gears.
Recall that all the libraries you download through Android Gears are housed in a special directory in your project folder called "Gears". To keep the size of your repository as small as possible, this folder is automatically ignored by creating an entry in your .gitignore file. To keep track of what gears are included in the project, another file GearSpecRegister is created that contains a list of all Gears associated with a given project. This helps those working in teams by declaring dependencies instead of including them in the repository.
A great example of this system's utility is when someone inherits a mature project using Android Gears. This person may checkout the repository and then sync (that is, download and install) the Gears declared in the GearSpecRegister. All of this is streamlined through the Manage Android Gears portion of the plugin, and is a simple as clicking a button.
*Note:** There is no need to actually open the GearSpecRegister file, but if you do, you will find a simple array of Gear Specs. If there is ever a conflict in this file due to more than one team member manipulating it, resolving the conflict is as easy as shuffling a few JSON objects around.
So you have created your shiny, new Android library and you want to make it available to all the world through Android Gears! Adding your library is as simple as initiating a properly formatted pull request to the Specs Repository. At the high level, the entire process is as follows:
.gearspec file through the Plugin or elsewhere that contains the Gear's metadata. See here for format.Your code must be stored somewhere online to be available for download through Android Gears. A few options are available with small variations. It is recommended that you use the Create Gear Spec portion of the Android Gears plugin, but, as this simply outputs a text file with JSON inside, you may also use your favorite text editor.
Method 1 - Module in Git
The first option is housing a module in a git repository on Github. If this is the method you have chosen, the source object of your .gearspec file might look something like the one from the Colours Library:
"source": {
"url": "https://github.com/MatthewYork/Colours.git",
"tag": "v1.0.0",
"source_files": "ColoursLibrary"
}Here, a url to the git repository is given as well as the tag associated with that specific release of Colours. Also, a directory "ColoursLibrary" is listed, meaning that the module is housed in a folder name "ColoursLibrary" at the root of the repository.
*Note When using modules, please ensure that all build variables in build.gradle are local in scope to the specified library path listed in source_files. If they are defined in the directory above in, say, the gradle.properties file, then they will be undefined when your library is retreived through Android Gears. This is because Android Gears only uses the directory specified in the source_files portion of the source object.
Method 2 - JAR in Git
The second way of housing a Gear is as a JAR file versioned through Git. Like method 1, you have a repository url and tag, but this time the source_files field contains the path to a JAR.
"source": {
"url": "https://github.com/AndroidGears/JodaTime.git",
"tag": "v2.3.0",
"source_files": "joda-time-2.3.jar"
}Method 3 - Static JAR
The final way of housing Gear is through a static JAR file. This choice is the only one that allows disassociation from a parent git repository. An example of this source might look something like this.
"source": {
"url": "http://mirrors.ibiblio.org/pub/mirrors/maven2/net/objectlab/kit/datecalc/datecalc-joda/1.0.1/datecalc-joda-1.0.1.jar",
"tag": null,
"source_files": null
}Pull requests to the Specs master repo will be reviewed and linted so as not to harm the integrity of the Specs repository. To avoid having your request denied, please use the linting and/or creation tools available in the plugin. We will review all requests as FIFO as possible and do our best to ensure the process is quick. If you would like to help become a reviewer, please contact [email protected]
We envision Android Gears to be a complete solution for managing dependencies in Android apps. As such, there are many enhancements that we would like to see in the future. We hope for much community involvement in the Android Gears project. Your pull requests and feature suggestions are welcome. Here are just a few things we have in mind.
Matthew York - Creator of Android Gears, Senior iOS and Android Developer for the Center for Advanced Public Safety
Aaron Fleshner - Creator of Android Gears, Senior Android Developer for the Center for Advanced Public Safety
Ben Gordon - Senior Developer at Curse and creator of androidgears.org
CocoaPods.org - The iOS dependency manager which much of the structure for Android Gears is based on.
JGit - The eclipse foundation project that handles git functionality in Android Gears
Java Swing - The wonderful GUI library that created all of the spectacular forms you see in Android Gears.
I would also like to thank God through whom all things live and move and have their being. Acts 17:28
The MIT License (MIT)
Copyright (c) 2014 Matthew York and Aaron Fleshner
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.