Project

General

Profile

DeveloperGuide » History » Version 33

Paul Kocialkowski, 09/01/2015 11:36 AM

1 31 Paul Kocialkowski
h1. Developer guide
2 1 Paul Kocialkowski
3 15 Paul Kocialkowski
{{>toc}}
4
5 3 Paul Kocialkowski
h2. Prerequisites
6
7 8 Paul Kocialkowski
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:
8 3 Paul Kocialkowski
* C language programming skills and the ability to understand other languages such as C++ and Java
9
* Makefile skills (no need to know every detail about it, a general idea of how Makefiles work is enough)
10
* git skills (basically, how to commit changes, send them to our repos, dealing with branches without making a mess, etc)
11 9 Paul Kocialkowski
  You can find some documentation about git at: http://git-scm.com/documentation
12 3 Paul Kocialkowski
13
If you think you can cope with the requirements, then developing on Replicant should cause you no particular issue.
14
15 26 Paul Kocialkowski
h3. Notes on writing free software replacements
16 3 Paul Kocialkowski
17
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.
18
19 1 Paul Kocialkowski
h2. Repositories
20
21
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.
22
It is better to create separate branches (that are not used by the official manifest branches) when your work is still in progress.
23
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.
24
25
h3. When creating a repository
26
27
In order to keep repo naming consistent, please name repositories by their name on the tree, replacing the @/@ by @_@.
28
For instance, when forking the CyanogenMod repo: @android_device_samsung_crespo@, rename it to @device_samsung_crespo@ on the Replicant repos.
29
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 @/@ by @_@.
30
31
h3. When creating a branch
32
33
Official replicant branches are named the following way:
34
* The @replicant-@ prefix
35
* The Replicant version
36
37
Such as: @replicant-2.3@ This should be used on the projects repositories as well as the manifest repository.
38
Any other branch should be considered as Work In Progress (WIP) and thus not be part of any official branch of the manifest.
39
40
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.
41 2 Paul Kocialkowski
42
h2. Upstreaming work
43
44
It is generally a good idea to send some changes back to upstream, assuming that they will benefit from it as well.
45
46
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.
47
Contact the interested developers on the upstream projects before attempting to send your replacement.
48
49
h3. CyanogenMod
50
51 10 Paul Kocialkowski
The CyanogenMod team uses Gerrit to manage patch submissions. The process to get your patch included in CyanogenMod repos is explained on their wiki: "Gerrit":http://wiki.cyanogenmod.org/w/Gerrit
52 3 Paul Kocialkowski
53 11 Paul Kocialkowski
You can push directly using git using the following scheme:
54
<pre>
55
git push ssh://<sshusername>@review.cyanogenmod.org:29418/CyanogenMod/cm-kernel HEAD:refs/for/<branchname>
56
</pre>
57
58 25 Paul Kocialkowski
h3. AOSP
59
60
The Android Open Source Project uses Gerrit to manage patch submissions. Some information about submitting patches to AOSP is available: http://source.android.com/source/submit-patches.html
61
62
You can push to AOSP's review using:
63
<pre>
64
git push https://android-review.googlesource.com/platform/system/core HEAD:refs/for/master
65
</pre>
66
67 3 Paul Kocialkowski
h2. Writing free software replacements
68
69
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):
70
* Look for interested people from other projects: CyanogenMod people are constantly fighting with non-free blobs and are sometimes happy to help replacing one.
71 6 Paul Kocialkowski
* Use tools such as @strings@, @objdump@ and @radare2@ against the non-free binary to have a better idea of how things work. (*Make sure this is legal where you live!*)
72 3 Paul Kocialkowski
* Try to make the non-free binary as verbose as possible by enabling all the possible debug options on the config file or such.
73
* Run the program in @strace@ and analyze the trace to understand what the program does.
74 1 Paul Kocialkowski
* Add verbose debug prints in the concerned kernel driver (with @printk@ and show them via the @dmesg@ tool).
75 6 Paul Kocialkowski
* Read the corresponding kernel driver: you can sometimes learn a lot by reading comments or headers.
76 3 Paul Kocialkowski
* Collect data out of the kernel driver (via debug prints) and out of the non-free binary (via debug prints on the upper-layer).
77
* 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.
78 17 Paul Kocialkowski
* 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!
79 4 Paul Kocialkowski
80 14 Paul Kocialkowski
h2. Wiki guidelines
81
82
In order the keep the wiki simple and consistent, a few guidelines must be followed when editing:
83
84 27 Paul Kocialkowski
* Every page in the wiki should be written in correct English, we do not aim to provide information in any other language
85 29 Paul Kocialkowski
* 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
86 14 Paul Kocialkowski
* The content on each page must be relevant *only* to the latest Replicant version: make sure to update the content with newer Replicant versions
87 21 Paul Kocialkowski
* Follow the devices naming convention (the @Galaxy S 3 (I9300)@ is not to be called @Samsung S3 GT-I9300@ or @Galaxy S III@)
88 1 Paul Kocialkowski
* Name the pages in a consistent manner ([[NexusSI902xFirmwares]] is not to be called [[FirmwaresOnTheI902xNexusS]])
89 29 Paul Kocialkowski
* Always ask before making a substantial change to the wiki
90 14 Paul Kocialkowski
91 16 Paul Kocialkowski
h2. Commonly-used terminology
92
93
In order to keep everything clear and consistent, we use the following terms with a precise meaning in mind:
94
* *Driver*: Software that is part of the *kernel* (builtin or as a module) and deals with communicating with the hardware
95
* *Hardware Abstraction Layer (HAL)*: Software that runs in *user-space* and deals with communicating with the hardware (usually through a kernel driver)
96
* *module*: Android HALs are also often called modules, so we may referrer to e.g. the @audio HAL@ as the @audio module@
97
* *blob*: Proprietary HAL
98 23 Paul Kocialkowski
* *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)
99 16 Paul Kocialkowski
100 33 Paul Kocialkowski
h2. New images release
101 1 Paul Kocialkowski
102 33 Paul Kocialkowski
# Modify the changelog in the vendor files:
103
<pre>
104
cd path/to/replicant-4.2/vendor/replicant
105
edit CHANGELOG.mkdn
106
git add CHANGELOG.mkdn
107
git commit -s -m "Replicant 4.2 0004 images release"
108
git push git@git.code.paulk.fr:replicant/vendor/replicant.git HEAD:replicant-4.2
109
</pre>
110
# Increment the release in the release scripts:
111
<pre>
112
cd path/to/release-scripts
113
edit release.sh
114
edit releasetag.sh
115
git add release.sh releasetag.sh
116
git commit -s -m "Replicant 4.2 0004 images release"
117
git push git@git.code.paulk.fr:release-scripts.git master
118
</pre>
119
# Tag all the repositories with the release tag script:
120
<pre>
121
path/to/release-scripts/releasetag.sh path/to/replicant-4.2
122
</pre>
123
# Tag the manifest:
124
<pre>
125
cd path/to/manifest
126
git tag -s -u 4A80EB23 -m "Replicant 4.2 0004 images release" -a replicant-4.2-0004 HEAD
127
git push git@git.replicant.us:manifest.git replicant-4.2-0004
128
</pre>
129
# Update prebuilts and start the build (with the Replicant keys and certificates installed)
130
# Release the images with the release script:
131
<pre>
132
mkdir -p path/to/images/replicant-4.2/0004
133
path/to/release-scripts/release.sh path/to/replicant-4.2 path/to/images/replicant-4.2/0004
134
</pre>
135
# Sign the binaries with the release script:
136
<pre>
137
path/to/release-scripts/release.sh path/to/replicant-4.2 path/to/images/replicant-4.2/0004 signatures
138
</pre>
139
# Compress the release files
140
<pre>
141
cd path/to/images/replicant-4.2
142
tar -cjf 0004.tar.bz2 0004
143
</pre>
144
# Upload the release to OSUOSL:
145
<pre>
146
scp 0004.tar.bz2 replicant@ftp-osl.osuosl.org:/home/replicant/data/images/replicant-4.2/
147
</pre>
148
# Unpack the release on OSUOSL, ensure permissions are correct
149
# Update [[ReplicantImages]] with the release
150
# Update each device's page with the release
151
# Update [[ReplicantStatus]] with the latest status
152
# Announce the release on the blog
153
# Update the release on the website and IRC topic
154 5 Paul Kocialkowski
155 33 Paul Kocialkowski
h2. New device documentation
156 22 Paul Kocialkowski
157 19 Paul Kocialkowski
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]])
158 13 Paul Kocialkowski
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]])
159 5 Paul Kocialkowski
3. Link the sub-pages to the main page in the index
160
4. Update the [[ReplicantStatus]] page of the wiki with the current status of the device
161
5. Modify the [[WikiStart]] page of the wiki and add the new device in the following sections:
162
* [[WikiStart#Replicant-status-on-phones|Replicant status on phones]]
163
* [[WikiStart#Installing-Replicant|Installing Replicant]]
164
* [[WikiStart#Building-Replicant|Building Replicant]]
165 7 Paul Kocialkowski
* [[WikiStart#Technical-infos-on-the-devices|Technical infos on the devices]]
166 24 Paul Kocialkowski
167 1 Paul Kocialkowski
6. Add new issues categories to the Replicant project redmine