Differences between revisions 35 and 36
Revision 35 as of 2011-03-16 21:01:39
Size: 10213
Editor: cpe-76-179-229-122
Revision 36 as of 2011-03-23 17:06:45
Size: 10440
Editor: cpe-76-179-229-122
Deletions are marked like this. Additions are marked like this.
Line 124: Line 124:
|| Crashers for which you'd like the user to get a stack trace || Could you please follow the instructions on and attach unity.log to this bug report? || ||

Debugging Central

This page is part of the debugging series — pages with debugging details for a variety of Ubuntu packages.


This page provides guidelines for filing bugs related to Unity, how to provide the debugging information required to analyze the issue, and how to triage Unity bugs.

Filing bugs

Technical issues

Use the standard ubuntu bug reporting tool as it gathers detailed information regarding your systems configuration. From the command line:

ubuntu-bug unity

When a crasher occurs on your system you should automatically see a dialog inviting you to report the issue. It will collect useful information from your system, automatically as well. But here is what you can also add to your bug report to help us confirm the issue more easily:

  • Provide the result of the command glxinfo. It contains important graphics information that can help us identify your issue. (glxinfo is provided by the package mesa-utils and is automatically run in Natty)
  • Provide the complete description of your GPU and how much video RAM it has. For instance, the market name of your graphics card may be Radeon HD 4650 or NVidia Geforce GTX 280. For embedded Intel GPU, you don't need to provide that information.
  • Your monitor resolution and screen setup (single, dual monitor, triple monitor)

If the dialog doesn't appear for some reason, see the "advanced" procedure below.

Even if the issue is actually in Compiz, it's still worth filing the bug against Unity, and we'll triage things to point to compiz as well. We're working very closely with the Compiz project. Now, if you know the bug is with Compiz, you can read the DebuggingCompiz page to help us get more info to solve the problem.

Design and usability issues

Because Unity is a user interface, all bugs that relate to user facing functionality need to be reported to the Unity design team. To report a user facing bug:

  • Report the bug against the Ayatana Design project (NOT the 'Unity' project)

  • Set the importance as you see fit
  • If the bug is urgent ping JohnLea on #ayatana on freenode.

Advanced debugging procedure

Stale crashers

If apport did not automatically report the issue, you can check that a crasher trace has been collected by looking into the /var/crash directory. You should see a filename containing 'compiz'.

ls -altr /var/crash to list them in chronological order.

To manually file a bug report using a crash file:

  • stay in your current X session
  • add a window manager from a TTY if needed, ie CTRL-ALT-F1, login, DISPLAY=:0 metacity --replace

  • then, from your X session, do: apport-bug -c /var/crash/<compiz crash file> and follow the procedure in the web page that should open shortly after you invoke this command. Note that focus issues may prevent the page to appear on the top, but look for a new browser window opened in your workspace.

Getting a stack trace

If for some reason apport was not enabled on your system, or if you have a reproducible issue we ask you to investigate, here is how you can generate a stack trace and inspect internal variables.

Ensure that you have the debugging symbols for the compiz, nux and unity packages.

Otherwise, from tty1 (Ctrl + Alt + F1)

$ unity --advanced-debug
GNU gdb (GDB) 7.2-ubuntu
Copyright (C) 2010 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
and "show warranty" for details.
This GDB was configured as "i686-linux-gnu".
For bug reporting instructions, please see:


(gdb) set logging file 'unity.log'
(gdb) set logging on
(gdb) b _exit
Function "_exit" not defined.
Make breakpoint pending on future shared library load? (y or [n])
[Answer yes (y)]

(gdb) run

[ and when compiz/unity crash, do...]

(gdb) bt full

[ then CTRL-D or re-run compiz to continue working ]

(gdb) run

You can also get a valgrind trace by running valgrind compiz --replace & in a terminal. This is a little bit slower to get because it runs compiz under emulation, but it does produce some output which isn't possible to get from gdb.

In extreme circumstances, we may ask you to use the crashhandler plugin from git and enable that in ccsm.

Triaging instructions

Standard Operating Procedures

Failure to follow these simple guidelines may result in severe bodily harm at the hands of lamalex and didrocks.

Keeping Upstream and Downstream statuses in sync

The upstream and downstream DX workflow is a little bit different than other projects. Since there is almost no distro patching of DX projects packaging bugs are an extremely small subset of bugs reported. For this reason, the workflow is as follows.

  1. Make sure the bug has both an upstream and downstream task.
  2. Keep statuses in sync.
    • Upstream is the master. Sync downstream statuses to upstream.
    • The exception here is for downstream packages that are fix released. Occasionally a fix will be cherry-picked from unreleased DX code, and released in a package to fix a critical issue. In this case do not sync the downstream status to the upstream.

Marking affected components

During triaging it is often the case that a bug reported will actually be a bug in a base component. When this occurs it is imperative to add a task on that component. For example, if a bug in nux is crashing unity, a task should be added against nux, and statuses should be sync'd with nux as the master.

Similarly, if a bug is reported against a component project a task should be added against the super project. For example if a reporter reports a bug in nux, bamf, dee, etc. a task should be filed against unity so that we can keep track of all of the components in one place.

Design Bugs

Some bugs are not technical defects, but behavioral, or visual ones. These often require input from the design team before they can be fixed. When a bug is determined to be a design bug, it should have an Ayatana design task added to it, and its Unity status should be set to incomplete with the tag needs-design. After a design decision has been reached the Unity status should be set to triaged as there is then enough information for the bug to be fixed. See also the Blocked waiting for design decision canned response.

An example (real world) design bug:

Canned Responses




Patch needs author to sign Canonical Contributer agreement

Looks good but before we merge it we need you to sign the Canonical contributer agreement. It's a quick, but necessary step to getting your code into the tree. Luckily you only need to sign it once and it will apply to all other Canonical project contributions you may make in the future. Make sure to CC David Barth when you send it in.

Blocked waiting for design decision

This bug is awaiting design feedback before progress can be made. Confirming that there is a question to be answered. Will be marked triaged when design gives a suitable direction forward.

Mark status as incomplete, and tag needs-design until design gives feedback.

Bug reported from clutter based Unity

This bug was reported against an old version of Unity. The new version of Unity is almost an entire rewrite based on very different technologies. Could you please check if this issue is present in the current version, and if it is reopen the bug to a NEW status.

Set the bug to WONTFIX, and let the user reopen it

Bugs that don't appear to be Unity related at all

The issue you're describing doesn't sound related to Unity. Could you log into a Gnome 2 session and see if this issue persists?

Crashers for which you'd like the user to get a stack trace

Could you please follow the instructions on and attach unity.log to this bug report?

Bug Tags

These tags allow isolation of bugs into smaller groups, providing an easier and faster way to work on specific issues.


Use case


Compiz bugs which are affecting Unity


Bugs reported by people who are running Unity


Smaller bugs that would be ideal for new contributors.



Testing a fix

Sometimes a developer might ask you to test a quick patch he came up with: check the Daily builds PPA to see if an updated version of Unity fixes the bugs you are experiencing. Be careful though, as those are daily builds that may break other things, and are to be considered unstable.

Known bugs

Known bugs, or missing features, are tracked in Launchpad and assigned to milestones to indicate when it is planned to be fixed and/or released.

Also see:

CategoryBugSquad CategoryDesktopTeam CategoryDebugging

Unity/FilingBugs (last edited 2012-05-06 19:54:52 by fabiomarconi)