Project

General

Profile

DeveloperGuide » History » Version 8

Paul Kocialkowski, 07/27/2013 09:08 PM

1 1 Paul Kocialkowski
h1. Developer Guide
2
3
These are guidelines that should be followed when doing Replicant development.
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
12
If you think you can cope with the requirements, then developing on Replicant should cause you no particular issue.
13
14
h3. Writing free software replacements
15
16
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.
17
18 1 Paul Kocialkowski
h2. Repositories
19
20
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.
21
It is better to create separate branches (that are not used by the official manifest branches) when your work is still in progress.
22
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.
23
24
h3. When creating a repository
25
26
In order to keep repo naming consistent, please name repositories by their name on the tree, replacing the @/@ by @_@.
27
For instance, when forking the CyanogenMod repo: @android_device_samsung_crespo@, rename it to @device_samsung_crespo@ on the Replicant repos.
28
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 @_@.
29
30
h3. When creating a branch
31
32
Official replicant branches are named the following way:
33
* The @replicant-@ prefix
34
* The Replicant version
35
36
Such as: @replicant-2.3@ This should be used on the projects repositories as well as the manifest repository.
37
Any other branch should be considered as Work In Progress (WIP) and thus not be part of any official branch of the manifest.
38
39
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.
40 2 Paul Kocialkowski
41
h2. Upstreaming work
42
43
It is generally a good idea to send some changes back to upstream, assuming that they will benefit from it as well.
44
45
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.
46
Contact the interested developers on the upstream projects before attempting to send your replacement.
47
48
h3. CyanogenMod
49
50
The CyanogenMod team uses Gerrit to manage patch submissions. The process to get your patch included in CyanogenMod repos is explained on their wiki: "Howto:Gerrit":http://wiki.cyanogenmod.org/wiki/Howto:_Gerrit
51 3 Paul Kocialkowski
52
h2. Writing free software replacements
53
54
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):
55
* Look for interested people from other projects: CyanogenMod people are constantly fighting with non-free blobs and are sometimes happy to help replacing one.
56 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!*)
57 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.
58
* Run the program in @strace@ and analyze the trace to understand what the program does.
59 1 Paul Kocialkowski
* Add verbose debug prints in the concerned kernel driver (with @printk@ and show them via the @dmesg@ tool).
60 6 Paul Kocialkowski
* Read the corresponding kernel driver: you can sometimes learn a lot by reading comments or headers.
61 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).
62
* 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.
63 4 Paul Kocialkowski
64
h2. New images release guide
65
66
1. Modify vendor/replicant/CHANGELOG.mkdn, commit and push
67
2. Update prebuilts (FDroid, Terminal Emulator, etc)
68
3. Start the build
69
4. Run the release script and ensure everything is OK
70
5. Compress the release files
71
<pre>tar -cjf 0005.tar.bz2 0005</pre>
72
6. Upload the release to ftp-osl.osuosl.org
73
<pre>scp -v 0005.tar.bz2 replicant@ftp-osl.osuosl.org:/home/replicant/data/images/replicant-2.3/0005.tar.bz2</pre>
74
7. Unpack the release, fix permissions
75
8. Modify [[ReplicantImages]], last image on every devices page
76
9. Announce the release on the blog, mailing list
77
10. Update the IRC topic
78 5 Paul Kocialkowski
79
h2. New device documentation guide
80
81
1. Create the device main page, following the naming guidelines applied to other devices (e.g. the Samsung Galaxy S II is called *Galaxy S2* and its page is [[GalaxyS2]])
82
2. Create all the related sub-pages (build guide and firmwares list at least), following the naming guidelines applied to other devices (e.g. [[GalaxyS2Build]] and [[GalaxyS2Firmwares]])
83
3. Create or update the installation process page for the device. If it is shared across devices, add the key combination for your device to the page.
84
4. Update the [[ReplicantStatus]] page of the wiki with the current status of the device
85
5. Modify the [[WikiStart]] page of the wiki and add the new device in the following sections:
86
* [[WikiStart#Replicant-status-on-phones|Replicant status on phones]]
87
* [[WikiStart#Installing-Replicant|Installing Replicant]]
88
* [[WikiStart#Building-Replicant|Building Replicant]]
89
* [[WikiStart#Technical-infos-on-the-devices|Technical infos on the devices]]
90
91 7 Paul Kocialkowski
7. Add new issues categories to the redmine Replicant project
92 5 Paul Kocialkowski
6. Add your device to the *Devices* and *Download* pages of the Blog