From: "Clément Pit--Claudel" <clement.pit@gmail.com>
To: Eli Zaretskii <eliz@gnu.org>
Cc: Emacs developers <emacs-devel@gnu.org>
Subject: Re: Bisecting display bugs
Date: Fri, 22 Jul 2016 14:55:36 -0400 [thread overview]
Message-ID: <20f2bf0b-8805-103d-9aeb-648317b270d6@gmail.com> (raw)
In-Reply-To: <837fcsdzkj.fsf@gnu.org>
[-- Attachment #1.1.1: Type: text/plain, Size: 98 bytes --]
> Thanks again for working on this.
Thanks for your comments! I've attached an updated patch.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1.1.2: 0001-Add-notes-about-using-git-bisect-to-pinpoint-Emacs-b.patch --]
[-- Type: text/x-diff; name="0001-Add-notes-about-using-git-bisect-to-pinpoint-Emacs-b.patch", Size: 5629 bytes --]
From bb565a03c35103c5ec60dd42582eafdbdc21b725 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Cl=C3=A9ment=20Pit--Claudel?= <clement.pitclaudel@live.com>
Date: Mon, 11 Jul 2016 01:47:01 +0200
Subject: [PATCH] Add notes about using `git bisect' to pinpoint Emacs bugs
* 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, 107 insertions(+), 1 deletion(-)
create mode 100644 admin/notes/bisecting
diff --git a/admin/notes/bisecting b/admin/notes/bisecting
new file mode 100644
index 0000000..3a335a4
--- /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 automate git bisect to find the commit
+that introduced an Emacs bug. Bisecting automatically works best if
+the bug is easy and quick to reproduce in a clean ‘emacs -Q’ instance.
+
+For an Emacs-independent tutorial on bisecting, run ‘git help bisect’.
+
+* Automating ‘git bisect’
+
+Use ‘git bisect run <some-shell-script>’ to automate the bisecting
+process. ‘<some-shell-script>’ should build Emacs, run your bug
+reproduction test, and return 0 if the current revision is good, 1 if
+it's bad, and 125 to skip the current revision.
+
+Concretely, ‘<some-shell-script>’ usually looks like this:
+
+ #!/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=/tmp/emacs.config.cache && make -j4) || exit 125
+
+ # Reproduce the bug, writing output somewhere
+ src/emacs -Q -l "../reproduce-the-bug.el" || exit 125
+
+Some caveats:
+
+- This script cleans Emacs' source directory with ‘git clean -xfd’, so
+ make sure your uncommitted changes are saved somewhere else.
+
+- You should produce the ‘../reproduce-your-bug.el’ script on your own
+ (it should check if the bug exists, and return the right error code
+ using ‘(kill-emacs EXIT-CODE)’).
+
+* Using ‘git bisect’ to find display-related bugs
+
+** Ways to programmatically detect display bugs
+
+Most bugs that manifest graphically can be checked for by
+programmatically inspecting the following elements:
+
+- text properties
+- window-start and window-end
+- posn-at-point
+- pos-visible-in-window-p
+- frame-geometry
+- window--dump-frame
+- frame--size-history
+- display-monitor-attributes-list
+- C-u C-x =
+- trace-redisplay and trace-to-stderr
+- dump-glyph-matrix and dump-frame-glyph-matrix
+
+** When the above fails
+
+Some bugs are only apparent through visual inspection. Since building
+Emacs takes a long time, it can be a pain to debug these manually.
+
+If your display bug has a clear manifestation in a screenshot of a
+particular portion of Emacs display, and you have a program, like
+'xwd', that can capture the content of the Emacs frame, and also have
+ImageMagick installed, you can automate the comparison of the
+redisplay results to make the bisection process fully automatic.
+
+Use the following template for ‘../reproduce-the-bug.el’: it requires
+ImageMagick (mogrify and identify) and xwd (if ‘xwd’ isn't available,
+you can use ImageMagick's ‘import’ tool, passing it a ‘-window’
+argument where ‘xwd’ wants ‘id’).
+
+ (defun image-checksum (img-fname)
+ "Compute a checksum of IMG-FNAME's image data."
+ (car (process-lines "identify" "-quiet" "-format" "%#" img-fname)))
+
+ (defun take-screenshot-and-exit (fname x y w h reference-fname)
+ "Save a screenshot of Emacs as FNAME, then exit.
+ X and Y are the coordinates of the top-left point of the area of
+ interest. W, and H are its dimensions. This function sets
+ Emacs' return code to 0 if the resulting screenshot matches
+ REFERENCE-FNAME, and 1 otherwise."
+ (let ((wid (frame-parameter nil 'outer-window-id))
+ (crop-spec (format "%dx%d+%d+%d" w h x y)))
+ (call-process "xwd" nil nil nil "-silent" "-id" wid "-out" fname)
+ (call-process "mogrify" nil nil nil fname "-crop" crop-spec))
+ (let ((same-picture (equal (image-checksum fname)
+ (image-checksum reference-fname))))
+ (kill-emacs (if same-picture 0 1))))
+
+ (defun main ()
+ ;; Reproduce your bug here
+ …
+ ;; Force a redisplay
+ (redisplay t)
+ ;; Insert rough X, Y, W, H values below
+ (run-with-timer 0 nil #'take-screenshot-and-exit
+ "screenshot.xwd" … … … … "reference-screenshot.xwd"))
+
+ (main)
+
+This script takes and crops a screenshot of Emacs after reproducing
+your bug, then compares the result to a reference (cropped)
+screenshot, and returns 0 if they match, and 1 otherwise. Cropping is
+useful to weed out unrelated display changes; try to include only a
+small portion of the screen containing your bug.
diff --git a/admin/notes/repo b/admin/notes/repo
index 3ab3da7..f169468 100644
--- a/admin/notes/repo
+++ b/admin/notes/repo
@@ -115,7 +115,8 @@ again.
* Bisecting
This is a semi-automated way to find the revision that introduced a bug.
-Browse 'git help bisect' for technical instructions.
+Browse 'git help bisect' and admin/notes/bisecting for technical
+instructions.
* Maintaining ChangeLog history
--
2.7.4
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]
next prev parent reply other threads:[~2016-07-22 18:55 UTC|newest]
Thread overview: 14+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-07-10 23:55 Bisecting display bugs Clément Pit--Claudel
2016-07-11 1:40 ` Óscar Fuentes
2016-07-11 14:22 ` Eli Zaretskii
2016-07-11 17:46 ` Óscar Fuentes
2016-07-11 17:54 ` Eli Zaretskii
2016-07-11 18:05 ` Óscar Fuentes
2016-07-22 18:55 ` Clément Pit--Claudel [this message]
2016-07-23 8:51 ` Eli Zaretskii
2016-07-23 13:22 ` Clément Pit--Claudel
2017-04-16 15:04 ` Clément Pit--Claudel
2017-04-16 15:32 ` Noam Postavsky
2017-04-16 20:57 ` Clément Pit-Claudel
2017-04-17 13:13 ` Herring, Davis
2017-04-17 13:43 ` Teemu Likonen
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20f2bf0b-8805-103d-9aeb-648317b270d6@gmail.com \
--to=clement.pit@gmail.com \
--cc=eliz@gnu.org \
--cc=emacs-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.