Skip to content

Commit 806e600

Browse files
dlechdlech
committed
Add page on debian packaging and page on ev3dev package archive.
1 parent c70e46f commit 806e600

File tree

3 files changed

+233
-3
lines changed

3 files changed

+233
-3
lines changed

‎docs/devtools/index.html‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,12 @@
11
---
2-
title: Developer Tools
2+
title: ev3dev Developer Tools
33
---
4-
4+
<p>
5+
This page contains information about the tools we use for developing ev3dev
6+
itself. Most of the information is not applicable for those just interested
7+
in writing programs that run on the ev3dev distribution.
8+
</p>
59
{% assign devtools=site.pages | where: "category", "devtools" | group_by: "subject" %}
6-
710
<ul>
811
{% for group in devtools %}
912
{% if group.name != "" %}

‎docs/devtools/installing-the-ev3dev-archive.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
title: Installing the ev3dev Archive
3+
subject: Development Setup
4+
---
5+
6+
We host a package archive that contains some packages we use for developing
7+
ev3dev itself. If you want to create your own ev3dev image files or work
8+
on one of our debian packages, you will need some packages from this archive.
9+
10+
If you just want to write programs for the EV3 itself, you don't need this.
11+
12+
Adding it is quite simple. Save the following as `/etc/apt/sources.list.d/ev3dev.list`.
13+
14+
deb http://ev3dev.org/debian trusty main
15+
#deb-src http://ev3dev.org/debian trusty main
16+
17+
Then trust the keyring by running...
18+
19+
sudo apt-key adv --keyserver pgp.mit.edu --recv-keys 2B210565
20+
21+
Now, lets try it out...
22+
23+
sudo apt-get update
24+
sudo apt-get install ev3dev-archive-keyring
25+
26+
If the package installs, then you are good to go.

‎docs/devtools/packaging-for-ev3dev.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
---
2+
title: Debian Packaging for ev3dev
3+
subject: Packaging
4+
---
5+
6+
* Table of Contents
7+
{:toc}
8+
9+
Being a Debian distribution, debian packaging is an important part of ev3dev.
10+
We maintain quite a few packages of our own and also modify some upstream
11+
packages.
12+
13+
## Setting up the Package Development Environment
14+
15+
Whether you are creating a new package or modifying an existing one, there are
16+
some tools that you are going to need. We currently use Ubuntu trusty as the
17+
development environment. (We will only support trusty, but any thing newer should
18+
work - same goes for jessie or newer on Debian). If you are using Windows or Mac
19+
you can use [VirtualBox] to run trusty in a virtual machine.
20+
21+
On your Ubuntu machine, you will need to install some packages.
22+
Note: If you are the kind of person that doesn't install recommends, make sure
23+
you install *all* of the recommended packages. If you don't know what
24+
"recommends" means, don't worry about it.
25+
26+
sudo apt-get install ubuntu-dev-tools qemu-user-static git-buildpackage
27+
28+
If you haven't already, you will also need to [add the ev3dev archive to apt][ev3dev-archive].
29+
Be sure to install the `ev3dev-archive-keyring` package. We will need it later.
30+
31+
(Optional) If you want to build packages for Raspberry Pi (1 - not 2), then you
32+
need to grab the patched [pbuilder-dist] script from [ev3dev-buildscripts].
33+
Save it somewhere in your `$PATH` (`/usr/local/bin` is a good choice).
34+
35+
If you have never used `git` before, you need to configure your name and email.
36+
In a terminal, run...
37+
38+
git config --global user.name "Your Name"
39+
git config --global user.email "yourname@example.com"
40+
41+
And the same info needs to be put into some environment variables. Paste the
42+
following to the end of `~/.bashrc`. You will need to start a new terminal
43+
or run `. ~/.bashrc` for these changes to take effect.
44+
45+
export DEBFULLNAME="Your Name"
46+
export DEBEMAIL="yourname@example.com"
47+
48+
And we need to configure [quilt] as well. Save the following to `~/.quiltrc`.
49+
50+
QUILT_PATCHES=debian/patches
51+
QUILT_NO_DIFF_INDEX=1
52+
QUILT_NO_DIFF_TIMESTAMPS=1
53+
QUILT_REFRESH_ARGS="-p ab"
54+
QUILT_DIFF_ARGS="--color=auto"
55+
56+
And one more config file. Save the following to `~/.pbuilerrc`.
57+
58+
APTKEYRINGS="/usr/share/keyrings/ev3dev-archive-keyring.gpg"
59+
# OTHERMIRROR is ignored when using pbuilder-dist. :-(
60+
# LP bug #1004579
61+
OTHERMIRROR="deb http://ev3dev.org/debian jessie main"
62+
63+
Finally, we need to setup `pbuilder-dist` to create a clean environment where
64+
the packages will actually be built. Run the following in a terminal...
65+
66+
# we have to work around a bug in pbuilder-dist.
67+
export OTHERMIRROR="deb http://ev3dev.org/debian jessie main"
68+
# For the EV3
69+
pbuilder-dist jessie armel create
70+
# For Raspberry Pi 1 (raspbian) - see "(Optional)" note above.
71+
pbuilder-dist jessie rpi create
72+
# For Raspberry Pi 2
73+
pbuilder-dist jessie armhf create
74+
75+
## Building an Existing Package
76+
77+
All ev3dev debian packages are hosted at <https://github.com/ev3dev>. To get the
78+
package source code, you need to clone it using `git`. If you are planning
79+
on making changes, you should [fork] the repository on GitHub first and then
80+
clone your repository so that you can push the changes back to GitHub. After you
81+
have forked the repository on GitHub, run...
82+
83+
# if you have ssh setup...
84+
git clone git@github.com:yourname/packagename
85+
# or if you don't have ssh...
86+
git clone https://github.com/yourname/packagename
87+
88+
We use [git-buildpackage] to manage packages, so to build a source package (.dsc),
89+
run...
90+
91+
git buildpackage -S -us -uc
92+
93+
The `-S` means to just build a source package and `-us -uc` means don't sign it.
94+
This creates several files in the parent directory.
95+
96+
If you have not run `pbuilder-dist` in a while, you should update it to make sure
97+
you have the most recent package list. Replace `armel` with other architectures
98+
as needed.
99+
100+
# Don't forget our workaround.
101+
export OTHERMIRROR="deb http://ev3dev.org/debian jessie main"
102+
pbuilder-dist jessie armel update
103+
104+
Now, we can actually build the package.
105+
106+
pbuilder-dist jessie armel build ../packagename_version.dsc
107+
108+
The .deb package(s) will be placed in `~/pbuilder/jessie-armel_result`. You can
109+
copy these files to your EV3 and install them.
110+
111+
## Modifying a Package
112+
113+
If you haven't already, you need to clone the package from git as described above.
114+
115+
Then we are going to tell git to ignore changes to the changelog. We are going
116+
to change that file, but we don't want to accidentally commit those changes.
117+
In the source code directory that you cloned, run the following...
118+
119+
git update-index --assume-unchanged debian/changelog
120+
121+
Now, we can change this file. Were going to use the `dch` program to do that.
122+
123+
dch --local yourname
124+
125+
This will add a new entry to the changelog and open it in a text editor for
126+
for changes. It will look something like this...
127+
128+
packagename (1.2.3-1yourname1) UNRELEASED; urgency=medium
129+
130+
*
131+
132+
-- Your Name <youremail@example.com> Fri, 31 Jul 2015 17:34:04 -0500
133+
134+
...
135+
136+
You don't need to make any changes - just close the text editor. **Tip:** After
137+
you install this package somewhere, you should bump the version number by running
138+
`dch --local yourname` again.
139+
140+
Now, you can make any changes you want to the source code. When you are done
141+
making changes, you can try them out by building the package as described above
142+
with one difference. You need to add an option so that it will not fail because
143+
of your changes.
144+
145+
git buildpackage -S -us -uc --git-ignore-new
146+
147+
Then use `pbuilder-dist` to build the binary package as describe above.
148+
149+
Once you are happy with your changes, commit them and push them back to GitHub.
150+
**Note:** Some packages use [quilt] for managing patches. If you want to figure
151+
out how that works, go for it, but it is not necessary. And even if you do use
152+
quilt, you will need to commit the quilt patch via git.
153+
154+
git add -i
155+
git commit
156+
git push
157+
158+
Then send us a [pull request] on GitHub.
159+
160+
## Releasing a Package
161+
162+
**Note:** This section is for ev3dev package maintainers. It does not apply to
163+
building packages for yourself.
164+
165+
1. Make sure you have thoroughly tested the changes and that the package builds
166+
and installs correctly using the methods described above.
167+
2. Run `lintian` on the test package(s) to ensure there are no packaging problems.
168+
3. Ensure any version information (other than `debian/changelog`) is properly
169+
updated to the new version.
170+
4. Delete any `debian/changelog` entries since the last release (you should
171+
have at least one for doing a test build).
172+
5. Make sure there are not any uncommited changes in git. If there are changes,
173+
commit them.
174+
6. Run `git-dch -R --commit` to create a `debian/changelog` entry. Edit it by
175+
hand if necessary.
176+
7. Run `git-buildpackage -S -us -uc --git-tag` to create the source package.
177+
8. Build the release packages using `pbuilder-dist`.
178+
9. Sign the `.changes` file in `~/pbuilder/<release>-<arch>_result/` using `debsign`.
179+
10. Push the new release to the ev3dev archive using `dput`.
180+
11. Push the git branch and tag to GitHub.
181+
12. Close any issues on GitHub that are fixed by this release with a message
182+
that includes the package name and version number.
183+
13. Add a news article to the ev3dev.org site announcing the release.
184+
185+
## Additional Resources
186+
187+
* [Debian Policy Manual] - make sure your package conforms to this
188+
* [Debian New Maintainers Guide] - good intro to debian packaging
189+
* [git-buildpackage] - useful info that is not in the man pages
190+
191+
192+
[VirtualBox]: https://www.virtualbox.org
193+
[ev3dev-archive]: {{ github.site.url }}/docs/devtools/installing-the-ev3dev-archive
194+
[pbuilder-dist]: https://raw.githubusercontent.com/ev3dev/ev3dev-buildscripts/master/pbuilder-dist
195+
[ev3dev-buildscripts]: https://github.com/ev3dev/ev3dev-buildscripts
196+
[quilt]: https://wiki.debian.org/UsingQuilt
197+
[fork]: https://help.github.com/articles/fork-a-repo/
198+
[git-buildpackage]: http://honk.sigxcpu.org/projects/git-buildpackage/manual-html/gbp.html
199+
[pull request]: https://help.github.com/articles/creating-a-pull-request/
200+
[Debian Policy Manual]: https://www.debian.org/doc/debian-policy/
201+
[Debian New Maintainers Guide]: https://www.debian.org/doc/manuals/maint-guide/

0 commit comments

Comments
 (0)