1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
|
B~ Reporting bugs
1~bugs Reporting bugs
Debian Live is far from being perfect, but we want to make it as close as possible to perfect - with your help. Do not hesitate to report a bug: it is better to fill a report twice than never. However, this chapter includes recommendations how to file good bug reports.
For the impatient:
_* Always check first the image status updates on our homepage at http://live.debian.net/ for known issues.
_* Always try to reproduce the bug with the *{most recent versions}* of live-build, live-boot, and live-config before submitting a bug report.
_* Try to give *{as specific information as possible}* about the bug. This includes (at least) the version of live-build, live-boot, and live-config used and the distribution of the live system you are building.
2~ Known issues
Because Debian *{testing}* and Debian *{unstable}* distributions are a moving target, when you specify either as the target system distribution, a successful build may not always be possible.
% FIXME:
If this causes too much difficulty for you, do not build a system based on *{testing}* or *{unstable}*, but rather, use *{stable}*. live-build does always default to the *{stable}* release.
Currently known issues are listed under the section 'status' on our homepage at http://live.debian.net/.
It is out of the scope of this manual to train you to correctly identify and fix problems in packages of the development distributions, however, there are two things you can always try: If a build fails when the target distribution is *{testing}*, try *{unstable}*. If *{unstable}* does not work either, revert to *{testing}* and pin the newer version of the failing package from *{unstable}* (see {APT pinning}#apt-pinning for details).
2~ Rebuild from scratch
To ensure that a particular bug is not caused by an uncleanly built system, please always rebuild the whole live system from scratch to see if the bug is reproducible.
2~ Use up-to-date packages
Using outdated packages can cause significant problems when trying to reproduce (and ultimately fix) your problem. Make sure your build system is up-to-date and any packages included in your image are up-to-date as well.
2~collect-information Collect information
Please provide enough information with your report. At least include the exact version of live-build version where the bug is encountered and steps to reproduce it. Please use common sense and include other relevant information if you think that it might help in solving the problem.
To make the most out of your bug report, we require at least the following information:
_* Architecture of the host system
_* Version of live-build on the host system
_* Version of live-boot on the live system
_* Version of live-config on the live system
_* Version of #{debootstrap}# and/or #{cdebootstrap}# on the host system
_* Architecture of the live system
_* Distribution of the live system
_* Version of the kernel on the live system
You can generate a log of the build process by using the #{tee}# command. We recommend doing this automatically with an #{auto/build}# script; (see {Managing a configuration}#managing-a-configuration for details).
code{
# lb build 2>&1 | tee build.log
}code
At boot time, live-boot stores a log in #{/var/log/live.log}# (or #{/var/log/live-boot.log}#).
Additionally, to rule out other errors, it is always a good idea to tar up your #{config/}# directory and upload it somewhere (do *{not}* send it as an attachment to the mailing list), so that we can try to reproduce the errors you encountered. If this is difficult (e.g. due to size) you can use the output of #{lb config --dump}# which produces a summary of your config tree (i.e. lists files in subdirectories of #{config/}# but does not include them).
Remember to send in any logs that were produced with English locale settings, e.g. run your live-build commands with a leading #{LC_ALL=C}# or #{LC_ALL=en_US}#.
2~ Isolate the failing case if possible
If possible, isolate the failing case to the smallest possible change that breaks. It is not always easy to do this, so if you can't manage it for your report, don't worry. However, if you plan your development cycle well, using small enough change sets per iteration, you may be able to isolate the problem by constructing a simpler 'base' configuration that closely matches your actual configuration plus just the broken change set added to it. If you have a hard time sorting out which of your changes broke, it may be that you are including too much in each change set and should develop in smaller increments.
2~ Use the correct package to report the bug against
Where does the bug appear?
3~ At build time whilst bootstrapping
live-build first bootstraps a basic Debian system with #{debootstrap}# or #{cdebootstrap}#. Depending on the bootstrapping tool used and the Debian distribution it is bootstrapping, it may fail. If a bug appears here, check if the error is related to a specific Debian package (most likely), or if it is related to bootstrapping tool itself.
In both cases, this is not a bug in Debian Live, but rather in Debian itself which we can not fix this directly. Please report such a bug against the bootstrapping tool or the failing package.
3~ At build time whilst installing packages
live-build installs additional packages from the Debian archive and depending on the Debian distribution used and the daily archive state, it can fail. If a bug appears here, check if the error is also reproducible on a normal system.
If this is the case, this is not a bug in Debian Live, but rather in Debian - please report it against the failing package. Running #{debootstrap}# separately from the Live system build or running #{lb bootstrap --debug}# will give you more information.
Also, if you are using a local mirror and/or any of sort of proxy and you are experiencing a problem, please always reproduce it first by bootstrapping from an official mirror.
3~ At boot time
If your image does not boot, please report it to the mailing list together with the information requested in {Collect information}#collect-information. Do not forget to mention, how/when the image failed, in Qemu, Virtualbox, VMWare or real hardware. If you are using a virtualization technology of any kind, please always run it on real hardware before reporting a bug. Providing a screenshot of the failure is also very helpful.
3~ At run time
If a package was successfully installed, but fails while actually running the Live system, this is probably a bug in Debian Live. However,
2~ Do the research
Before filing the bug, please search the web for the particular error message or symptom you are getting. As it is highly unlikely that you are the only person experiencing a particular problem, there is always a chance that it has been discussed elsewhere, and a possible solution, patch, or workaround has been proposed.
You should pay particular attention to the Debian Live mailing list, as well as the homepage, as these are likely to contain the most up-to-date information. If such information exists, always include the references to it in your bug report.
In addition, you should check the current bug lists for live-build, live-boot, and live-config to see whether something similar has been reported already.
2~ Where to report bugs
The Debian Live project keeps track of all bugs in the Debian Bug Tracking System (BTS). For information on how to use the system, please see http://bugs.debian.org/. You can also submit the bugs by using the #{reportbug}# command from the package with the same name.
In general, you should report build time errors against the live-build package, boot time errors against live-boot, and run time errors against live-config. If you are unsure of which package is appropriate or need more help before submitting a bug report, please send a message to the mailing list and we will help you to figure it out.
Please note that bugs found in distributions derived from Debian (such as Ubuntu and others) should *{not}* be reported to the Debian BTS unless they can be also reproduced on a Debian system using official Debian packages.
|
