From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: =?UTF-8?Q?Cl=c3=a9ment_Pit--Claudel?= Newsgroups: gmane.emacs.devel Subject: Bisecting display bugs Date: Mon, 11 Jul 2016 01:55:31 +0200 Message-ID: <5782E073.6000505@gmail.com> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="8TQu6Cp3XHWhIdbi6kKU1HUCCuPhX9FfJ" X-Trace: ger.gmane.org 1468194997 9399 80.91.229.3 (10 Jul 2016 23:56:37 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 10 Jul 2016 23:56:37 +0000 (UTC) To: Emacs developers Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Jul 11 01:56:25 2016 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1bMOaG-00005U-5W for ged-emacs-devel@m.gmane.org; Mon, 11 Jul 2016 01:56:24 +0200 Original-Received: from localhost ([::1]:57218 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bMOaC-00086r-19 for ged-emacs-devel@m.gmane.org; Sun, 10 Jul 2016 19:56:20 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:48341) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bMOZW-00082R-91 for emacs-devel@gnu.org; Sun, 10 Jul 2016 19:55:39 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bMOZR-0007C2-4J for emacs-devel@gnu.org; Sun, 10 Jul 2016 19:55:38 -0400 Original-Received: from mout.kundenserver.de ([217.72.192.73]:55155) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bMOZQ-0007Bv-OX for emacs-devel@gnu.org; Sun, 10 Jul 2016 19:55:33 -0400 Original-Received: from [192.168.1.82] ([109.24.225.43]) by mrelayeu.kundenserver.de (mreue102) with ESMTPSA (Nemesis) id 0M4qhJ-1bCb1C0qrt-00yxnv for ; Mon, 11 Jul 2016 01:55:31 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Thunderbird/38.8.0 X-Provags-ID: V03:K0:GXhCvDf9ZIIdbkNoZbqtQgjJvGcb0UllE79oGLBksZLGnGQEE12 Xx4+UQ+WloN8iDlUezFU4N9Losy4j6P43tm4fAOcgtCM2MIhLjiArAa/nKuZk7BdXfwBRmF c+lS63HDDiz75vie1TDPH735x4xP42gMbXFDN9b07uku5tTd0UQAW53t9TVZsUwXG6gi/Q0 gee4FUinsgndFNFIt4nIA== X-UI-Out-Filterresults: notjunk:1;V01:K0:II7Z18wtDoU=:3+j3V49ke7h8htYqOqnPkw jtZpAjK1xdLQvkMFUMqZFfOXto2GAyfnxDSGX8WwBpzjC0h9Pd+qkUq2lC2+vYuNPy73r/7mh NeAgK/OhdaCJdKxpKs8T/XB5OngWxSR0JLOica0vVyFKPZv9N+dyxCc4caXD06PHs9V06vDGn oFOKnuJX6AxP8/WCcYve2GHj9ZqfXIA8DBLYrRYqFmAxqZ6p3IYzAv6cEdp5J632ffHptoaKR j2MX6HLYJWZGVLlwnacvdUX8h9Y2BYJ64va16/cslB1ki/hM42a+lpc+iQrAXx2VX1greQJBj fROmc+PLSn+OiRFiiy4Rb4RL738tBqXD8+yBgmT7xflPBABRogBw3CLem7u+KTleUbV4Xermk X+UMCxvR2wYZ9iW9hPvJ72+brTpICWobG1wafCb534Hb6ZlwOeVxHBOelLd+xLZreTIunrF9d KMFl/CDJW+vO0Ap/cpysNG7I55bwSPcWz4e1llX2x3IEo5wXB1yOXiK+UDeBkZFOuhZdVC36y hbtyIunWRKP+UZ017BdJfGk8ZaogH9CqD8TAQyxEDxrTsk4zKDRfX2go9qRScvbxHlOyBZiDj pSTYRyaT3plS8zNBX41TPyNj9CwPwnC8QCh2VuBNsT42KbfzRCAk43JJXGZboXjTmXNKA6FzQ vUB0tMtrbTK3BiMnyHQ6XkhyE9lTRmFpfUcHrE/dAP+3OLF088ly06R0FI2KwxjFetec= X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 217.72.192.73 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:205529 Archived-At: This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --8TQu6Cp3XHWhIdbi6kKU1HUCCuPhX9FfJ Content-Type: multipart/mixed; boundary="VP3keS7XBgARFTXSE0JewIKNJD0bwCPJo" From: =?UTF-8?Q?Cl=c3=a9ment_Pit--Claudel?= To: Emacs developers Message-ID: <5782E073.6000505@gmail.com> Subject: Bisecting display bugs --VP3keS7XBgARFTXSE0JewIKNJD0bwCPJo Content-Type: multipart/mixed; boundary="------------050603090906060601040004" This is a multi-part message in MIME format. --------------050603090906060601040004 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Hey emacs-devel, I've written up notes while bisecting a display bug (#23938) on master. = Since it didn't seem easy to identify the problem automatically from Elis= p, I used a small `git bisect run' script that automatically captured, cr= opped, and compared screenshots of Emacs against a known-good reference. = All in all, things worked nicely: git bisect took 4 hours to complete, b= ut it didn't require any interaction after starting. I attached my notes. Is there interest in including them in admin/notes/= ? Cheers, Cl=C3=A9ment. --------------050603090906060601040004 Content-Type: text/x-diff; name="0001-Add-notes-about-using-git-bisect-to-pinpoint-Emacs-b.patch" Content-Transfer-Encoding: quoted-printable Content-Disposition: attachment; filename*0="0001-Add-notes-about-using-git-bisect-to-pinpoint-Emacs-b.pa"; filename*1="tch" =46rom 15196c30e37aa937b121abcd7d95d35e0b3350d8 Mon Sep 17 00:00:00 2001 From: =3D?UTF-8?q?Cl=3DC3=3DA9ment=3D20Pit--Claudel?=3D Date: Mon, 11 Jul 2016 01:47:01 +0200 Subject: [PATCH] Add notes about using `git bisect' to pinpoint Emacs bug= s * admin/notes/bisecting: New file. * admin/notes/repo: Add pointer to admin/notes/bisecting. --- admin/notes/bisecting | 105 ++++++++++++++++++++++++++++++++++++++++++++= ++++++ admin/notes/repo | 3 +- 2 files changed, 106 insertions(+), 2 deletions(-) create mode 100644 admin/notes/bisecting diff --git a/admin/notes/bisecting b/admin/notes/bisecting new file mode 100644 index 0000000..4efb5cc --- /dev/null +++ b/admin/notes/bisecting @@ -0,0 +1,105 @@ +HOW TO USE GIT BISECT TO PINPOINT EMACS BUGS -*- outline -*- + +This documents explains how to use git bisect to find the commit that +introduced an Emacs bug. Bisecting works best if the bug is easy and +relatively quick to reproduce in a clean =E2=80=98emacs -Q=E2=80=99 inst= ance. + +For general information about bisecting, use =E2=80=98M-x man git-bisect= =E2=80=99. +This document contains quick-start instructions and Emacs-specific +tips. + +* Bisecting Emacs bugs + +First, find a recipe that reproduces the bug in emacs -Q. Then use +this recipe to locate a revision in which the bug doesn't happen. If +it's a new bug, a not-too-recent revision could do; otherwise, +checking for the bug previous releases of Emacs works well. + +Then, run the following command to start bisecting + + git bisect start + + is usually HEAD in practice. + +Git will then check out revisions between these two bounds,; at each +step, you need to run =E2=80=98git bisect good=E2=80=99 or =E2=80=98git = bisect bad=E2=80=99 to inform +git of the status of the current revision: =E2=80=98bad=E2=80=99 if it h= as the bug; +good if it doesn't. + +If Emacs' build is broken in the current revision, use =E2=80=98git bise= ct +skip=E2=80=99 to move to a neighboring revision. + +** Automating =E2=80=98git bisect=E2=80=99 + +You can also write =E2=80=98git bisect run =E2=80=99 = to automate +the process. =E2=80=98=E2=80=99 should build Emacs, = run your bug +reproduction test, and return 0 if the current revision is good, and 1 +otherwise. Returning 125 is equivalent to doing =E2=80=98git bisect ski= p=E2=80=99. + +Concretely, =E2=80=98=E2=80=99 usually looks like thi= s: + + #!/usr/bin/env bash + + # Remove leftovers from previous runs + git clean -xfd > /dev/null + # Build Emacs and skip commit if build fails + (./autogen.sh && ./configure --cache-file=3D/tmp/emacs.config.cache = && make -j4) || exit 125 + + # Reproduce the bug, writing output somewhere + src/emacs -Q -l "../reproduce-the-bug.el" || exit 125 + # Remove leftovers again + git clean -xfd > /dev/null + # Analyze output and produce exit code + cmp ../reference-output current-output + +Some caveats: + +- This script cleans Emacs' source directory with =E2=80=98git clean -xf= d=E2=80=99, so + make sure your uncommitted changes are saved somewhere else. + +- You should produce the =E2=80=98../reproduce-your-bug.el=E2=80=99 scri= pt on your own + (it should check if the bug exists, and save a different output to a + file named =E2=80=98current-output=E2=80=99 based on the result of tha= t check), as + well as a file =E2=80=98../reference-output=E2=80=99 containing the ex= pected output + in the good case. + +** Using =E2=80=98git bisect=E2=80=99 to find display-related bugs + +Most bugs that manifest graphically can be checked for by +programmatically inspecting text properties, but some are only +apparent through visual inspection. Since building Emacs takes a long +time, it can be a pain to debug these manually. + +Fortunately, it's relatively easy to bisect such bugs automatically. +Use the following template for =E2=80=98../reproduce-the-bug.el=E2=80=99= : + + (defun take-screenshot-and-exit (fname x y w h) + "Save a screenshot of Emacs as FNAME, then exit. + X and Y are the coordinates of the top-left point of the area of int= erest. + W, and H are its dimensions." + (let ((window-id (frame-parameter nil 'outer-window-id))) + (call-process "xwd" nil nil nil "-silent" "-id" window-id "-out"= fname)) + (call-process "mogrify" nil nil nil fname "-crop" (format "%dx%d+%= d+%d" w h x y)) + (kill-emacs)) + + (defun main () + ;; Reproduce your bug here + =E2=80=A6 + ;; Force a redisplay + (redisplay t) + ;; Insert rough X, Y, W, H values below + (run-with-timer 0 nil #'take-screenshot-and-exit "screenshot.xwd" = =E2=80=A6 =E2=80=A6 =E2=80=A6 =E2=80=A6)) + + (main) + +This script makes a screenshot of Emacs after reproducing your bug (if +=E2=80=98xwd=E2=80=99 isn't available, you can use ImageMagick's =E2=80=98= import=E2=80=99 tool, +passing it a =E2=80=98-window=E2=80=99 argument where =E2=80=98xwd=E2=80= =99 wants =E2=80=98id=E2=80=99). Cropping the +image is useful to weed out unrelated display changes; try to include +only a small portion of the screen containing your bug. + +Then to produce the right exit code use ImageMagick's =E2=80=98identify=E2= =80=99 tool: + + cmp <(identify -quiet -format "%#" "../screenshot.xwd") <(identify -= quiet -format "%#" "../good.xwd") + +=E2=80=98good.xwd=E2=80=99 should be the image produced by your script i= n the good state. diff --git a/admin/notes/repo b/admin/notes/repo index 3ab3da7..60373bd 100644 --- a/admin/notes/repo +++ b/admin/notes/repo @@ -114,8 +114,7 @@ again. =20 * Bisecting =20 -This is a semi-automated way to find the revision that introduced a bug.= -Browse 'git help bisect' for technical instructions. +See admin/notes/bisecting. =20 * Maintaining ChangeLog history =20 --=20 2.9.0 --------------050603090906060601040004-- --VP3keS7XBgARFTXSE0JewIKNJD0bwCPJo-- --8TQu6Cp3XHWhIdbi6kKU1HUCCuPhX9FfJ Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.22 (GNU/Linux) iQIcBAEBAgAGBQJXguBzAAoJEPqg+cTm90wjsZIQAJp80Issgyp4a9kHzv00WlD+ vyUz2Pja4ZEUwOA1795h42BedFFPLrxvMrVJ0ViEh+iUgUB5RaXUXv2gXhEmMcn7 FVjpUPTdsTgrNT97wGvLj7m4swCsjH1fGykwrtZN9M/cwq2UOSew4j0rOvfa1qJH wr42dAPDyUpGPCZvQSUPV2gALbvwfWi65RkQl+TliWTaMNSgogwwe1/vWeXf+bKX Wb8wqi5Hnh60WifL7FhjWoymW1FFhhGVWV/pyE4CTYS6cOw33H/sQapSeVFBHXb6 oYLaLOgdRAMld/GykGu1h8G27NPkwi7MD8YAktY6YJOaWy8BULtsQb6gXGA4+gVd lLFinpjnuZvCkI/QjaDs6vI/RGovRGNPrwAvdwzmgq6pH1ZZUDuWMcjlprUFxdEF adQWKkovJI8NN4sjCOYriwOykhsPMCP9SM8DBVnWcP7tBjkXd2Wp1f/RcCjApyXO CYM0G1wn6qC9utRxN/Xx2qVbB2mY45Z5wP2vE4VaH1v+4LY5m4A4AhdMZID62TOi xCM4KmafIr5hlHL7D92XpqWa4ae98+g6XPidRKMxdv7FbGS/G3CLln+ro2xXPJ9V D8ZxyCLEk26fc2Ennpjopv1UHYbxETquRVkWm9Try3KIDiRBV2EK24UO6SPT1yqV FR8ef6b+7f5PhuQAlD7p =d1o/ -----END PGP SIGNATURE----- --8TQu6Cp3XHWhIdbi6kKU1HUCCuPhX9FfJ--