- Developer guide
Prerequisites¶Developing on Replicant isn't much harder than developing on any other free software project as it doesn't require specific knowledge. In fact, you'll probably learn a lot along the way regarding how hardware works, how the Android system is composed, how the kernel works, etc, but you don't need to know all of this to start. However a basic set of skills is required, among which:
- C language programming skills and the ability to understand other languages such as C++ and Java
- Makefile skills (no need to know every detail about it, a general idea of how Makefiles work is enough)
- git skills (basically, how to commit changes, send them to our repos, dealing with branches without making a mess, etc)
You can find some documentation about Git at: http://git-scm.com/documentation
If you think you can cope with the requirements, then developing on Replicant should cause you no particular issue.
Notes on writing free software replacements¶
Writing free software replacements for non-free components may require more skills depending on what you're trying to achieve, though there may be people with the adequate knowledge to help you and from whom you will likely learn a lot.
Code hosting and submitting patches¶
Replicant's source code is hosted at git.replicant.us. If you plan to regularly contribute to Replicant and if you don't yet have a code hosting provider that satisfies your needs, you are welcome to host your Replicant-related projects there under your own username, You only need to contact one of Replicant's developers and ask for an account. Please include in your request the name, username and Email address that should be used for creating your account.
Replicant currently doesn't accept merge requests. There are two ways to get your patches included: You can either send them to the mailing list or open an issue on the issue tracker and attach the patches to the issue. Replicant developers will then review your changes.
See the Git documentation for creating a patch. Patches can be send with
git send-email. If it's too much hassle for you to set up
git send-email, sending the patches with your favorite mail client should be fine, too.
When working with Replicant repos, make sure to avoid breaking things. For instance, if you push a commit introducing a compilation error, it will break the whole build process.
It is better to create separate branches (that are not used by the official manifest branches) when your work is still in progress.
Creating branches that add debug infos on a particular topic is usually a good idea since it will save you time next time you want to debug the same component.
When creating a repository¶
In order to keep repo naming consistent, please name repositories by their name on the tree, replacing the
For instance, when forking the LineageOS repo:
android_device_samsung_crespo, rename it to
device_samsung_crespo on the Replicant repos.
This creates a more consistent way of naming repositories and makes it easier when pushing: just look at the location in the source tree and replace
When creating a branch¶Official Replicant branches are named the following way:
- The Replicant version
replicant-2.3 This should be used on the projects repositories as well as the manifest repository.
Any other branch should be considered as Work In Progress (WIP) and thus not be part of any official branch of the manifest.
There is although one exception, with the
master branch, that can be used by any project and be in any manifest given that the code held in the
master branch will work on any Replicant version.
It is generally a good idea to send some changes back to upstream, assuming that they will benefit from it as well.
When it is about the replacement of a non-free component present in the upstream systems, make sure that your replacement is reliable and complete.
Contact the interested developers on the upstream projects before attempting to send your replacement.
The LineageOS team uses Gerrit to manage patch submissions. The process to get your patch included in LineageOS repos is explained on their wiki: Gerrit
You can also push directly using git using the following scheme (untested):
git push ssh://<sshusername>@review.lineageos.org:29418/LineageOS/<projectname> HEAD:refs/for/<branchname>
The Android Open Source Project uses Gerrit to manage patch submissions. Some information about submitting patches to AOSP is available: https://source.android.com/source/submit-patches.html
You can push to AOSP's review using:
git push https://android-review.googlesource.com/platform/system/core HEAD:refs/for/master
Writing free software replacements¶Here are some tips that may help you achieving a free software replacement for a specific component (some may be more or less relevant regarding the nature of what the component does):
- Look for interested people from other projects: LineageOS people are constantly fighting with non-free blobs and are sometimes happy to help replacing one.
- Use tools such as
radare2against the non-free binary to have a better idea of how things work. (Make sure this is legal where you live!)
- Try to make the non-free binary as verbose as possible by enabling all the possible debug options on the config file or such.
- Run the program in
straceand analyze the trace to understand what the program does.
- Add verbose debug prints in the concerned kernel driver (with
printkand show them via the
- Read the corresponding kernel driver: you can sometimes learn a lot by reading comments or headers.
- Collect data out of the kernel driver (via debug prints) and out of the non-free binary (via debug prints on the upper-layer).
- If there is a mathematical algorithm involved, force the values returned by the kernel to the non-free binary and analyze how it reacts, for instance with spreadsheet software.
- If you're directly dealing with a hardware component, try to find a datasheet for the chip, it may hold precious details. In the best case, you may also be able to find a reference software implementation!
In order the keep the wiki simple and consistent, a few guidelines must be followed when editing.Regarding the content:
- Only Replicant-specific topics should be covered by the wiki: there is no point in writing usage guides for generic Android aspects, such as the user interface.
- The content on each page should only be relevant to the latest Replicant version: make sure to update the content with newer Replicant versions.
- Substantial changes must be discussed before modifying the wiki.
- Every page in the wiki has to be written in correct English, we do not aim to provide information in any other language.
- Readers shouldn't be addressed directly: Instead, what is described should always be the subject of sentences.
- Links to pages should be incorporated in text (Instructions to install ADB shouldn't be: Instructions to install ADB: ToolsInstallation).
- Pages must be named in a consistent manner (NexusSI902xFirmwares is not to be called FirmwaresOnTheI902xNexusS).
- Common prefixes and suffixes should be used for naming new pages (BuildDependenciesInstallation is not to be called InstallationOfBuildDependencies).
- Page and section names should always be named using nouns, not verbs, either active or not (DeveloperGuide is not to be called DevelopingGuide).
- Page titles shouldn't contain space or any delimiter character (such as - or_) but use upper-case characters as word delimiters (BuildDependenciesInstallation is not to be called Build_dependencies_installation).
- Page titles as shown on the page should use lower-case when upper-case is not needed, even if the page name uses upper-case as word delimiters.
- Devices should be named after their model number and codename, without mention of the manufacturer.
- Common device naming conventions should be followed consistently (the
Galaxy S 3 (I9300)is not to be called
Samsung S3 GT-I9300or
Galaxy S III).
Commonly-used terminology¶In order to keep everything clear and consistent, we use the following terms with a precise meaning in mind:
- Driver: Software that is part of the kernel (builtin or as a module) and deals with communicating with the hardware
- Hardware Abstraction Layer (HAL): Software that runs in user-space and deals with communicating with the hardware (usually through a kernel driver)
- module: Android HALs are also often called modules, so we may referrer to e.g. the
audio HALas the
- blob: Proprietary HAL
- firmware: Software that does not run on the main processor (the CPU) but rather in a separate chip (e.g. the Wi-Fi firmwares runs on the Wi-Fi chip)
New images release¶
- Modify the changelog in the vendor files:
cd path/to/replicant-4.2/vendor/replicant edit CHANGELOG.mkdn git add CHANGELOG.mkdn git commit -s -m "Replicant 4.2 0004 images release" git push firstname.lastname@example.org:replicant/vendor/replicant.git HEAD:replicant-4.2
- Increment the release in the release scripts:
cd path/to/release-scripts edit release.sh edit releasetag.sh git add release.sh releasetag.sh git commit -s -m "Replicant 4.2 0004 images release" git push email@example.com:release-scripts.git master
- Tag all the repositories with the release tag script:
- Tag the manifest:
cd path/to/manifest git tag -s -u 4A80EB23 -m "Replicant 4.2 0004 images release" -a replicant-4.2-0004 HEAD git push firstname.lastname@example.org:manifest.git replicant-4.2-0004
- Update prebuilts and start the build (with the Replicant keys and certificates installed)
- Release the images with the release script:
mkdir -p path/to/images/replicant-4.2/0004 path/to/release-scripts/release.sh path/to/replicant-4.2 path/to/images/replicant-4.2/0004
- Sign the binaries with the release script:
path/to/release-scripts/release.sh path/to/replicant-4.2 path/to/images/replicant-4.2/0004 signatures
- Compress the release files
cd path/to/images/replicant-4.2 tar -cjf 0004.tar.bz2 0004
- Upload the release to OSUOSL:
scp 0004.tar.bz2 email@example.com:/home/replicant/data/images/replicant-4.2/
- Unpack the release on OSUOSL, ensure permissions are correct
- Update ReplicantImages with the release
- Update each device's page with the release
- Update ReplicantStatus with the latest status
- Announce the release on the blog
- Update the release on the website and IRC topic
New device documentation¶1. Create the device main page, following the naming guidelines applied to other devices (e.g. the Samsung Galaxy S II GT-I9100 is called Galaxy S 2 (I9100) and its page is GalaxyS2I9100)
2. Create all the related sub-pages (build guide, install guide and firmwares list at least), following the naming guidelines applied to other devices (e.g. GalaxyS2I9100Build, GalaxyS2I9100Installation and GalaxyS2I9100Firmwares)
3. Link the sub-pages to the main page in the index
4. Update the ReplicantStatus page of the wiki with the current status of the device
5. Modify the WikiStart page of the wiki and add the new device in the following sections:
6. Add new issues categories to the Replicant project Redmine
Wiki License: Creative Commons BY-SA