From 5c1676dfe6d2f3c837a5e074117b45613fd29a72 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 20:30:19 +0200 Subject: Adding upstream version 2.10.34. Signed-off-by: Daniel Baumann --- devel-docs/performance-logs/Makefile.am | 10 + devel-docs/performance-logs/Makefile.in | 755 +++++++++++++++++++++ .../performance-logs/dashboard-add-marker.png | Bin 0 -> 15936 bytes .../performance-logs/dashboard-start-recording.png | Bin 0 -> 16212 bytes .../performance-logs/dashboard-stop-recording.png | Bin 0 -> 15890 bytes .../performance-logs/new-performance-issue.png | Bin 0 -> 108368 bytes .../performance-log-parameters.png | Bin 0 -> 8187 bytes .../performance-logs/performance-log-viewer.png | Bin 0 -> 159718 bytes devel-docs/performance-logs/performance-logs.md | 651 ++++++++++++++++++ 9 files changed, 1416 insertions(+) create mode 100644 devel-docs/performance-logs/Makefile.am create mode 100644 devel-docs/performance-logs/Makefile.in create mode 100644 devel-docs/performance-logs/dashboard-add-marker.png create mode 100644 devel-docs/performance-logs/dashboard-start-recording.png create mode 100644 devel-docs/performance-logs/dashboard-stop-recording.png create mode 100644 devel-docs/performance-logs/new-performance-issue.png create mode 100644 devel-docs/performance-logs/performance-log-parameters.png create mode 100644 devel-docs/performance-logs/performance-log-viewer.png create mode 100644 devel-docs/performance-logs/performance-logs.md (limited to 'devel-docs/performance-logs') diff --git a/devel-docs/performance-logs/Makefile.am b/devel-docs/performance-logs/Makefile.am new file mode 100644 index 0000000..9f97b4b --- /dev/null +++ b/devel-docs/performance-logs/Makefile.am @@ -0,0 +1,10 @@ +## Process this file with automake to produce Makefile.in + +EXTRA_DIST = \ + dashboard-add-marker.png \ + dashboard-start-recording.png \ + dashboard-stop-recording.png \ + performance-log-parameters.png \ + new-performance-issue.png \ + performance-log-viewer.png \ + performance-logs.md diff --git a/devel-docs/performance-logs/Makefile.in b/devel-docs/performance-logs/Makefile.in new file mode 100644 index 0000000..1beb5ab --- /dev/null +++ b/devel-docs/performance-logs/Makefile.in @@ -0,0 +1,755 @@ +# Makefile.in generated by automake 1.16.3 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994-2020 Free Software Foundation, Inc. + +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ +VPATH = @srcdir@ +am__is_gnu_make = { \ + if test -z '$(MAKELEVEL)'; then \ + false; \ + elif test -n '$(MAKE_HOST)'; then \ + true; \ + elif test -n '$(MAKE_VERSION)' && test -n '$(CURDIR)'; then \ + true; \ + else \ + false; \ + fi; \ +} +am__make_running_with_option = \ + case $${target_option-} in \ + ?) ;; \ + *) echo "am__make_running_with_option: internal error: invalid" \ + "target option '$${target_option-}' specified" >&2; \ + exit 1;; \ + esac; \ + has_opt=no; \ + sane_makeflags=$$MAKEFLAGS; \ + if $(am__is_gnu_make); then \ + sane_makeflags=$$MFLAGS; \ + else \ + case $$MAKEFLAGS in \ + *\\[\ \ ]*) \ + bs=\\; \ + sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \ + | sed "s/$$bs$$bs[$$bs $$bs ]*//g"`;; \ + esac; \ + fi; \ + skip_next=no; \ + strip_trailopt () \ + { \ + flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \ + }; \ + for flg in $$sane_makeflags; do \ + test $$skip_next = yes && { skip_next=no; continue; }; \ + case $$flg in \ + *=*|--*) continue;; \ + -*I) strip_trailopt 'I'; skip_next=yes;; \ + -*I?*) strip_trailopt 'I';; \ + -*O) strip_trailopt 'O'; skip_next=yes;; \ + -*O?*) strip_trailopt 'O';; \ + -*l) strip_trailopt 'l'; skip_next=yes;; \ + -*l?*) strip_trailopt 'l';; \ + -[dEDm]) skip_next=yes;; \ + -[JT]) skip_next=yes;; \ + esac; \ + case $$flg in \ + *$$target_option*) has_opt=yes; break;; \ + esac; \ + done; \ + test $$has_opt = yes +am__make_dryrun = (target_option=n; $(am__make_running_with_option)) +am__make_keepgoing = (target_option=k; $(am__make_running_with_option)) +pkgdatadir = $(datadir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkglibexecdir = $(libexecdir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +subdir = devel-docs/performance-logs +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/acinclude.m4 \ + $(top_srcdir)/m4macros/alsa.m4 \ + $(top_srcdir)/m4macros/ax_compare_version.m4 \ + $(top_srcdir)/m4macros/ax_cxx_compile_stdcxx.m4 \ + $(top_srcdir)/m4macros/ax_gcc_func_attribute.m4 \ + $(top_srcdir)/m4macros/ax_prog_cc_for_build.m4 \ + $(top_srcdir)/m4macros/ax_prog_perl_version.m4 \ + $(top_srcdir)/m4macros/detectcflags.m4 \ + $(top_srcdir)/m4macros/pythondev.m4 $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +DIST_COMMON = $(srcdir)/Makefile.am $(am__DIST_COMMON) +mkinstalldirs = $(install_sh) -d +CONFIG_HEADER = $(top_builddir)/config.h +CONFIG_CLEAN_FILES = +CONFIG_CLEAN_VPATH_FILES = +AM_V_P = $(am__v_P_@AM_V@) +am__v_P_ = $(am__v_P_@AM_DEFAULT_V@) +am__v_P_0 = false +am__v_P_1 = : +AM_V_GEN = $(am__v_GEN_@AM_V@) +am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@) +am__v_GEN_0 = @echo " GEN " $@; +am__v_GEN_1 = +AM_V_at = $(am__v_at_@AM_V@) +am__v_at_ = $(am__v_at_@AM_DEFAULT_V@) +am__v_at_0 = @ +am__v_at_1 = +SOURCES = +DIST_SOURCES = +am__can_run_installinfo = \ + case $$AM_UPDATE_INFO_DIR in \ + n|no|NO) false;; \ + *) (install-info --version) >/dev/null 2>&1;; \ + esac +am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP) +am__DIST_COMMON = $(srcdir)/Makefile.in +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +AA_LIBS = @AA_LIBS@ +ACLOCAL = @ACLOCAL@ +ALLOCA = @ALLOCA@ +ALL_LINGUAS = @ALL_LINGUAS@ +ALSA_CFLAGS = @ALSA_CFLAGS@ +ALSA_LIBS = @ALSA_LIBS@ +ALTIVEC_EXTRA_CFLAGS = @ALTIVEC_EXTRA_CFLAGS@ +AMTAR = @AMTAR@ +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ +APPSTREAM_UTIL = @APPSTREAM_UTIL@ +AR = @AR@ +AS = @AS@ +ATK_CFLAGS = @ATK_CFLAGS@ +ATK_LIBS = @ATK_LIBS@ +ATK_REQUIRED_VERSION = @ATK_REQUIRED_VERSION@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +BABL_CFLAGS = @BABL_CFLAGS@ +BABL_LIBS = @BABL_LIBS@ +BABL_REQUIRED_VERSION = @BABL_REQUIRED_VERSION@ +BUG_REPORT_URL = @BUG_REPORT_URL@ +BUILD_EXEEXT = @BUILD_EXEEXT@ +BUILD_OBJEXT = @BUILD_OBJEXT@ +BZIP2_LIBS = @BZIP2_LIBS@ +CAIRO_CFLAGS = @CAIRO_CFLAGS@ +CAIRO_LIBS = @CAIRO_LIBS@ +CAIRO_PDF_CFLAGS = @CAIRO_PDF_CFLAGS@ +CAIRO_PDF_LIBS = @CAIRO_PDF_LIBS@ +CAIRO_PDF_REQUIRED_VERSION = @CAIRO_PDF_REQUIRED_VERSION@ +CAIRO_REQUIRED_VERSION = @CAIRO_REQUIRED_VERSION@ +CATALOGS = @CATALOGS@ +CATOBJEXT = @CATOBJEXT@ +CC = @CC@ +CCAS = @CCAS@ +CCASDEPMODE = @CCASDEPMODE@ +CCASFLAGS = @CCASFLAGS@ +CCDEPMODE = @CCDEPMODE@ +CC_FOR_BUILD = @CC_FOR_BUILD@ +CC_VERSION = @CC_VERSION@ +CFLAGS = @CFLAGS@ +CFLAGS_FOR_BUILD = @CFLAGS_FOR_BUILD@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CPPFLAGS_FOR_BUILD = @CPPFLAGS_FOR_BUILD@ +CPP_FOR_BUILD = @CPP_FOR_BUILD@ +CXX = @CXX@ +CXXCPP = @CXXCPP@ +CXXDEPMODE = @CXXDEPMODE@ +CXXFLAGS = @CXXFLAGS@ +CYGPATH_W = @CYGPATH_W@ +DATADIRNAME = @DATADIRNAME@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +DESKTOP_DATADIR = @DESKTOP_DATADIR@ +DESKTOP_FILE_VALIDATE = @DESKTOP_FILE_VALIDATE@ +DLLTOOL = @DLLTOOL@ +DOC_SHOOTER = @DOC_SHOOTER@ +DSYMUTIL = @DSYMUTIL@ +DUMPBIN = @DUMPBIN@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +EXEEXT = @EXEEXT@ +FGREP = @FGREP@ +FILE_AA = @FILE_AA@ +FILE_EXR = @FILE_EXR@ +FILE_HEIF = @FILE_HEIF@ +FILE_JP2_LOAD = @FILE_JP2_LOAD@ +FILE_JPEGXL = @FILE_JPEGXL@ +FILE_MNG = @FILE_MNG@ +FILE_PDF_SAVE = @FILE_PDF_SAVE@ +FILE_PS = @FILE_PS@ +FILE_WMF = @FILE_WMF@ +FILE_XMC = @FILE_XMC@ +FILE_XPM = @FILE_XPM@ +FONTCONFIG_CFLAGS = @FONTCONFIG_CFLAGS@ +FONTCONFIG_LIBS = @FONTCONFIG_LIBS@ +FONTCONFIG_REQUIRED_VERSION = @FONTCONFIG_REQUIRED_VERSION@ +FREETYPE2_REQUIRED_VERSION = @FREETYPE2_REQUIRED_VERSION@ +FREETYPE_CFLAGS = @FREETYPE_CFLAGS@ +FREETYPE_LIBS = @FREETYPE_LIBS@ +GDBUS_CODEGEN = @GDBUS_CODEGEN@ +GDK_PIXBUF_CFLAGS = @GDK_PIXBUF_CFLAGS@ +GDK_PIXBUF_CSOURCE = @GDK_PIXBUF_CSOURCE@ +GDK_PIXBUF_LIBS = @GDK_PIXBUF_LIBS@ +GDK_PIXBUF_REQUIRED_VERSION = @GDK_PIXBUF_REQUIRED_VERSION@ +GEGL = @GEGL@ +GEGL_CFLAGS = @GEGL_CFLAGS@ +GEGL_LIBS = @GEGL_LIBS@ +GEGL_MAJOR_MINOR_VERSION = @GEGL_MAJOR_MINOR_VERSION@ +GEGL_REQUIRED_VERSION = @GEGL_REQUIRED_VERSION@ +GETTEXT_PACKAGE = @GETTEXT_PACKAGE@ +GEXIV2_CFLAGS = @GEXIV2_CFLAGS@ +GEXIV2_LIBS = @GEXIV2_LIBS@ +GEXIV2_REQUIRED_VERSION = @GEXIV2_REQUIRED_VERSION@ +GIMP_API_VERSION = @GIMP_API_VERSION@ +GIMP_APP_VERSION = @GIMP_APP_VERSION@ +GIMP_BINARY_AGE = @GIMP_BINARY_AGE@ +GIMP_COMMAND = @GIMP_COMMAND@ +GIMP_DATA_VERSION = @GIMP_DATA_VERSION@ +GIMP_FULL_NAME = @GIMP_FULL_NAME@ +GIMP_INTERFACE_AGE = @GIMP_INTERFACE_AGE@ +GIMP_MAJOR_VERSION = @GIMP_MAJOR_VERSION@ +GIMP_MICRO_VERSION = @GIMP_MICRO_VERSION@ +GIMP_MINOR_VERSION = @GIMP_MINOR_VERSION@ +GIMP_MKENUMS = @GIMP_MKENUMS@ +GIMP_MODULES = @GIMP_MODULES@ +GIMP_PACKAGE_REVISION = @GIMP_PACKAGE_REVISION@ +GIMP_PKGCONFIG_VERSION = @GIMP_PKGCONFIG_VERSION@ +GIMP_PLUGINS = @GIMP_PLUGINS@ +GIMP_PLUGIN_VERSION = @GIMP_PLUGIN_VERSION@ +GIMP_REAL_VERSION = @GIMP_REAL_VERSION@ +GIMP_RELEASE = @GIMP_RELEASE@ +GIMP_SYSCONF_VERSION = @GIMP_SYSCONF_VERSION@ +GIMP_TOOL_VERSION = @GIMP_TOOL_VERSION@ +GIMP_UNSTABLE = @GIMP_UNSTABLE@ +GIMP_USER_VERSION = @GIMP_USER_VERSION@ +GIMP_VERSION = @GIMP_VERSION@ +GIO_CFLAGS = @GIO_CFLAGS@ +GIO_LIBS = @GIO_LIBS@ +GIO_UNIX_CFLAGS = @GIO_UNIX_CFLAGS@ +GIO_UNIX_LIBS = @GIO_UNIX_LIBS@ +GIO_WINDOWS_CFLAGS = @GIO_WINDOWS_CFLAGS@ +GIO_WINDOWS_LIBS = @GIO_WINDOWS_LIBS@ +GLIB_CFLAGS = @GLIB_CFLAGS@ +GLIB_COMPILE_RESOURCES = @GLIB_COMPILE_RESOURCES@ +GLIB_GENMARSHAL = @GLIB_GENMARSHAL@ +GLIB_LIBS = @GLIB_LIBS@ +GLIB_MKENUMS = @GLIB_MKENUMS@ +GLIB_REQUIRED_VERSION = @GLIB_REQUIRED_VERSION@ +GMODULE_NO_EXPORT_CFLAGS = @GMODULE_NO_EXPORT_CFLAGS@ +GMODULE_NO_EXPORT_LIBS = @GMODULE_NO_EXPORT_LIBS@ +GMOFILES = @GMOFILES@ +GMSGFMT = @GMSGFMT@ +GOBJECT_QUERY = @GOBJECT_QUERY@ +GREP = @GREP@ +GS_LIBS = @GS_LIBS@ +GTKDOC_CHECK = @GTKDOC_CHECK@ +GTKDOC_CHECK_PATH = @GTKDOC_CHECK_PATH@ +GTKDOC_DEPS_CFLAGS = @GTKDOC_DEPS_CFLAGS@ +GTKDOC_DEPS_LIBS = @GTKDOC_DEPS_LIBS@ +GTKDOC_MKPDF = @GTKDOC_MKPDF@ +GTKDOC_REBASE = @GTKDOC_REBASE@ +GTK_CFLAGS = @GTK_CFLAGS@ +GTK_LIBS = @GTK_LIBS@ +GTK_MAC_INTEGRATION_CFLAGS = @GTK_MAC_INTEGRATION_CFLAGS@ +GTK_MAC_INTEGRATION_LIBS = @GTK_MAC_INTEGRATION_LIBS@ +GTK_REQUIRED_VERSION = @GTK_REQUIRED_VERSION@ +GTK_UPDATE_ICON_CACHE = @GTK_UPDATE_ICON_CACHE@ +GUDEV_CFLAGS = @GUDEV_CFLAGS@ +GUDEV_LIBS = @GUDEV_LIBS@ +HARFBUZZ_CFLAGS = @HARFBUZZ_CFLAGS@ +HARFBUZZ_LIBS = @HARFBUZZ_LIBS@ +HARFBUZZ_REQUIRED_VERSION = @HARFBUZZ_REQUIRED_VERSION@ +HAVE_CXX14 = @HAVE_CXX14@ +HAVE_FINITE = @HAVE_FINITE@ +HAVE_ISFINITE = @HAVE_ISFINITE@ +HAVE_VFORK = @HAVE_VFORK@ +HOST_GLIB_COMPILE_RESOURCES = @HOST_GLIB_COMPILE_RESOURCES@ +HTML_DIR = @HTML_DIR@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +INSTOBJEXT = @INSTOBJEXT@ +INTLLIBS = @INTLLIBS@ +INTLTOOL_EXTRACT = @INTLTOOL_EXTRACT@ +INTLTOOL_MERGE = @INTLTOOL_MERGE@ +INTLTOOL_PERL = @INTLTOOL_PERL@ +INTLTOOL_REQUIRED_VERSION = @INTLTOOL_REQUIRED_VERSION@ +INTLTOOL_UPDATE = @INTLTOOL_UPDATE@ +INTLTOOL_V_MERGE = @INTLTOOL_V_MERGE@ +INTLTOOL_V_MERGE_OPTIONS = @INTLTOOL_V_MERGE_OPTIONS@ +INTLTOOL__v_MERGE_ = @INTLTOOL__v_MERGE_@ +INTLTOOL__v_MERGE_0 = @INTLTOOL__v_MERGE_0@ +INTL_MACOSX_LIBS = @INTL_MACOSX_LIBS@ +ISO_CODES_LOCALEDIR = @ISO_CODES_LOCALEDIR@ +ISO_CODES_LOCATION = @ISO_CODES_LOCATION@ +JPEG_LIBS = @JPEG_LIBS@ +JSON_GLIB_CFLAGS = @JSON_GLIB_CFLAGS@ +JSON_GLIB_LIBS = @JSON_GLIB_LIBS@ +JXL_CFLAGS = @JXL_CFLAGS@ +JXL_LIBS = @JXL_LIBS@ +JXL_THREADS_CFLAGS = @JXL_THREADS_CFLAGS@ +JXL_THREADS_LIBS = @JXL_THREADS_LIBS@ +LCMS_CFLAGS = @LCMS_CFLAGS@ +LCMS_LIBS = @LCMS_LIBS@ +LCMS_REQUIRED_VERSION = @LCMS_REQUIRED_VERSION@ +LD = @LD@ +LDFLAGS = @LDFLAGS@ +LDFLAGS_FOR_BUILD = @LDFLAGS_FOR_BUILD@ +LIBBACKTRACE_LIBS = @LIBBACKTRACE_LIBS@ +LIBHEIF_CFLAGS = @LIBHEIF_CFLAGS@ +LIBHEIF_LIBS = @LIBHEIF_LIBS@ +LIBHEIF_REQUIRED_VERSION = @LIBHEIF_REQUIRED_VERSION@ +LIBJXL_REQUIRED_VERSION = @LIBJXL_REQUIRED_VERSION@ +LIBLZMA_REQUIRED_VERSION = @LIBLZMA_REQUIRED_VERSION@ +LIBMYPAINT_CFLAGS = @LIBMYPAINT_CFLAGS@ +LIBMYPAINT_LIBS = @LIBMYPAINT_LIBS@ +LIBMYPAINT_REQUIRED_VERSION = @LIBMYPAINT_REQUIRED_VERSION@ +LIBOBJS = @LIBOBJS@ +LIBPNG_REQUIRED_VERSION = @LIBPNG_REQUIRED_VERSION@ +LIBS = @LIBS@ +LIBTOOL = @LIBTOOL@ +LIBUNWIND_CFLAGS = @LIBUNWIND_CFLAGS@ +LIBUNWIND_LIBS = @LIBUNWIND_LIBS@ +LIBUNWIND_REQUIRED_VERSION = @LIBUNWIND_REQUIRED_VERSION@ +LIPO = @LIPO@ +LN_S = @LN_S@ +LTLIBOBJS = @LTLIBOBJS@ +LT_CURRENT_MINUS_AGE = @LT_CURRENT_MINUS_AGE@ +LT_SYS_LIBRARY_PATH = @LT_SYS_LIBRARY_PATH@ +LT_VERSION_INFO = @LT_VERSION_INFO@ +LZMA_CFLAGS = @LZMA_CFLAGS@ +LZMA_LIBS = @LZMA_LIBS@ +MAIL = @MAIL@ +MAINT = @MAINT@ +MAKEINFO = @MAKEINFO@ +MANIFEST_TOOL = @MANIFEST_TOOL@ +MIME_INFO_CFLAGS = @MIME_INFO_CFLAGS@ +MIME_INFO_LIBS = @MIME_INFO_LIBS@ +MIME_TYPES = @MIME_TYPES@ +MKDIR_P = @MKDIR_P@ +MKINSTALLDIRS = @MKINSTALLDIRS@ +MMX_EXTRA_CFLAGS = @MMX_EXTRA_CFLAGS@ +MNG_CFLAGS = @MNG_CFLAGS@ +MNG_LIBS = @MNG_LIBS@ +MSGFMT = @MSGFMT@ +MSGFMT_OPTS = @MSGFMT_OPTS@ +MSGMERGE = @MSGMERGE@ +MYPAINT_BRUSHES_CFLAGS = @MYPAINT_BRUSHES_CFLAGS@ +MYPAINT_BRUSHES_LIBS = @MYPAINT_BRUSHES_LIBS@ +NATIVE_GLIB_CFLAGS = @NATIVE_GLIB_CFLAGS@ +NATIVE_GLIB_LIBS = @NATIVE_GLIB_LIBS@ +NM = @NM@ +NMEDIT = @NMEDIT@ +OBJDUMP = @OBJDUMP@ +OBJEXT = @OBJEXT@ +OPENEXR_CFLAGS = @OPENEXR_CFLAGS@ +OPENEXR_LIBS = @OPENEXR_LIBS@ +OPENEXR_REQUIRED_VERSION = @OPENEXR_REQUIRED_VERSION@ +OPENJPEG_CFLAGS = @OPENJPEG_CFLAGS@ +OPENJPEG_LIBS = @OPENJPEG_LIBS@ +OPENJPEG_REQUIRED_VERSION = @OPENJPEG_REQUIRED_VERSION@ +OTOOL = @OTOOL@ +OTOOL64 = @OTOOL64@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_URL = @PACKAGE_URL@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PANGOCAIRO_CFLAGS = @PANGOCAIRO_CFLAGS@ +PANGOCAIRO_LIBS = @PANGOCAIRO_LIBS@ +PANGOCAIRO_REQUIRED_VERSION = @PANGOCAIRO_REQUIRED_VERSION@ +PATHSEP = @PATHSEP@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +PERL = @PERL@ +PERL_REQUIRED_VERSION = @PERL_REQUIRED_VERSION@ +PERL_VERSION = @PERL_VERSION@ +PKG_CONFIG = @PKG_CONFIG@ +PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@ +PKG_CONFIG_PATH = @PKG_CONFIG_PATH@ +PNG_CFLAGS = @PNG_CFLAGS@ +PNG_LIBS = @PNG_LIBS@ +POFILES = @POFILES@ +POPPLER_CFLAGS = @POPPLER_CFLAGS@ +POPPLER_DATA_CFLAGS = @POPPLER_DATA_CFLAGS@ +POPPLER_DATA_LIBS = @POPPLER_DATA_LIBS@ +POPPLER_DATA_REQUIRED_VERSION = @POPPLER_DATA_REQUIRED_VERSION@ +POPPLER_LIBS = @POPPLER_LIBS@ +POPPLER_REQUIRED_VERSION = @POPPLER_REQUIRED_VERSION@ +POSUB = @POSUB@ +PO_IN_DATADIR_FALSE = @PO_IN_DATADIR_FALSE@ +PO_IN_DATADIR_TRUE = @PO_IN_DATADIR_TRUE@ +PYBIN_PATH = @PYBIN_PATH@ +PYCAIRO_CFLAGS = @PYCAIRO_CFLAGS@ +PYCAIRO_LIBS = @PYCAIRO_LIBS@ +PYGIMP_EXTRA_CFLAGS = @PYGIMP_EXTRA_CFLAGS@ +PYGTK_CFLAGS = @PYGTK_CFLAGS@ +PYGTK_CODEGEN = @PYGTK_CODEGEN@ +PYGTK_DEFSDIR = @PYGTK_DEFSDIR@ +PYGTK_LIBS = @PYGTK_LIBS@ +PYLINK_LIBS = @PYLINK_LIBS@ +PYTHON = @PYTHON@ +PYTHON2_REQUIRED_VERSION = @PYTHON2_REQUIRED_VERSION@ +PYTHON_EXEC_PREFIX = @PYTHON_EXEC_PREFIX@ +PYTHON_INCLUDES = @PYTHON_INCLUDES@ +PYTHON_PLATFORM = @PYTHON_PLATFORM@ +PYTHON_PREFIX = @PYTHON_PREFIX@ +PYTHON_VERSION = @PYTHON_VERSION@ +RANLIB = @RANLIB@ +RSVG_REQUIRED_VERSION = @RSVG_REQUIRED_VERSION@ +RT_LIBS = @RT_LIBS@ +SCREENSHOT_LIBS = @SCREENSHOT_LIBS@ +SED = @SED@ +SENDMAIL = @SENDMAIL@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +SOCKET_LIBS = @SOCKET_LIBS@ +SSE2_EXTRA_CFLAGS = @SSE2_EXTRA_CFLAGS@ +SSE4_1_EXTRA_CFLAGS = @SSE4_1_EXTRA_CFLAGS@ +SSE_EXTRA_CFLAGS = @SSE_EXTRA_CFLAGS@ +STRIP = @STRIP@ +SVG_CFLAGS = @SVG_CFLAGS@ +SVG_LIBS = @SVG_LIBS@ +SYMPREFIX = @SYMPREFIX@ +TIFF_LIBS = @TIFF_LIBS@ +USE_NLS = @USE_NLS@ +VERSION = @VERSION@ +WEBKIT_CFLAGS = @WEBKIT_CFLAGS@ +WEBKIT_LIBS = @WEBKIT_LIBS@ +WEBKIT_REQUIRED_VERSION = @WEBKIT_REQUIRED_VERSION@ +WEBPDEMUX_CFLAGS = @WEBPDEMUX_CFLAGS@ +WEBPDEMUX_LIBS = @WEBPDEMUX_LIBS@ +WEBPMUX_CFLAGS = @WEBPMUX_CFLAGS@ +WEBPMUX_LIBS = @WEBPMUX_LIBS@ +WEBP_CFLAGS = @WEBP_CFLAGS@ +WEBP_LIBS = @WEBP_LIBS@ +WEBP_REQUIRED_VERSION = @WEBP_REQUIRED_VERSION@ +WEB_PAGE = @WEB_PAGE@ +WIN32_LARGE_ADDRESS_AWARE = @WIN32_LARGE_ADDRESS_AWARE@ +WINDRES = @WINDRES@ +WMF_CFLAGS = @WMF_CFLAGS@ +WMF_CONFIG = @WMF_CONFIG@ +WMF_LIBS = @WMF_LIBS@ +WMF_REQUIRED_VERSION = @WMF_REQUIRED_VERSION@ +XDG_EMAIL = @XDG_EMAIL@ +XFIXES_CFLAGS = @XFIXES_CFLAGS@ +XFIXES_LIBS = @XFIXES_LIBS@ +XGETTEXT = @XGETTEXT@ +XGETTEXT_REQUIRED_VERSION = @XGETTEXT_REQUIRED_VERSION@ +XMC_CFLAGS = @XMC_CFLAGS@ +XMC_LIBS = @XMC_LIBS@ +XMKMF = @XMKMF@ +XMLLINT = @XMLLINT@ +XMU_LIBS = @XMU_LIBS@ +XPM_LIBS = @XPM_LIBS@ +XSLTPROC = @XSLTPROC@ +XVFB_RUN = @XVFB_RUN@ +X_CFLAGS = @X_CFLAGS@ +X_EXTRA_LIBS = @X_EXTRA_LIBS@ +X_LIBS = @X_LIBS@ +X_PRE_LIBS = @X_PRE_LIBS@ +Z_LIBS = @Z_LIBS@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_AR = @ac_ct_AR@ +ac_ct_CC = @ac_ct_CC@ +ac_ct_CC_FOR_BUILD = @ac_ct_CC_FOR_BUILD@ +ac_ct_CXX = @ac_ct_CXX@ +ac_ct_DUMPBIN = @ac_ct_DUMPBIN@ +am__include = @am__include@ +am__leading_dot = @am__leading_dot@ +am__quote = @am__quote@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +docdir = @docdir@ +dvidir = @dvidir@ +exec_prefix = @exec_prefix@ +gimpdatadir = @gimpdatadir@ +gimpdir = @gimpdir@ +gimplocaledir = @gimplocaledir@ +gimpplugindir = @gimpplugindir@ +gimpsysconfdir = @gimpsysconfdir@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +intltool__v_merge_options_ = @intltool__v_merge_options_@ +intltool__v_merge_options_0 = @intltool__v_merge_options_0@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +manpage_gimpdir = @manpage_gimpdir@ +mkdir_p = @mkdir_p@ +ms_librarian = @ms_librarian@ +mypaint_brushes_dir = @mypaint_brushes_dir@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +pkgpyexecdir = @pkgpyexecdir@ +pkgpythondir = @pkgpythondir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +pyexecdir = @pyexecdir@ +pythondir = @pythondir@ +runstatedir = @runstatedir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +top_build_prefix = @top_build_prefix@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +EXTRA_DIST = \ + dashboard-add-marker.png \ + dashboard-start-recording.png \ + dashboard-stop-recording.png \ + performance-log-parameters.png \ + new-performance-issue.png \ + performance-log-viewer.png \ + performance-logs.md + +all: all-am + +.SUFFIXES: +$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \ + && { if test -f $@; then exit 0; else break; fi; }; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu devel-docs/performance-logs/Makefile'; \ + $(am__cd) $(top_srcdir) && \ + $(AUTOMAKE) --gnu devel-docs/performance-logs/Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__maybe_remake_depfiles)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__maybe_remake_depfiles);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(am__aclocal_m4_deps): + +mostlyclean-libtool: + -rm -f *.lo + +clean-libtool: + -rm -rf .libs _libs +tags TAGS: + +ctags CTAGS: + +cscope cscopelist: + + +distdir: $(BUILT_SOURCES) + $(MAKE) $(AM_MAKEFLAGS) distdir-am + +distdir-am: $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d "$(distdir)/$$file"; then \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \ + else \ + test -f "$(distdir)/$$file" \ + || cp -p $$d/$$file "$(distdir)/$$file" \ + || exit 1; \ + fi; \ + done +check-am: all-am +check: check-am +all-am: Makefile +installdirs: +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + if test -z '$(STRIP)'; then \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + install; \ + else \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \ + fi +mostlyclean-generic: + +clean-generic: + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +clean: clean-am + +clean-am: clean-generic clean-libtool mostlyclean-am + +distclean: distclean-am + -rm -f Makefile +distclean-am: clean-am distclean-generic + +dvi: dvi-am + +dvi-am: + +html: html-am + +html-am: + +info: info-am + +info-am: + +install-data-am: + +install-dvi: install-dvi-am + +install-dvi-am: + +install-exec-am: + +install-html: install-html-am + +install-html-am: + +install-info: install-info-am + +install-info-am: + +install-man: + +install-pdf: install-pdf-am + +install-pdf-am: + +install-ps: install-ps-am + +install-ps-am: + +installcheck-am: + +maintainer-clean: maintainer-clean-am + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-generic + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-generic mostlyclean-libtool + +pdf: pdf-am + +pdf-am: + +ps: ps-am + +ps-am: + +uninstall-am: + +.MAKE: install-am install-strip + +.PHONY: all all-am check check-am clean clean-generic clean-libtool \ + cscopelist-am ctags-am distclean distclean-generic \ + distclean-libtool distdir dvi dvi-am html html-am info info-am \ + install install-am install-data install-data-am install-dvi \ + install-dvi-am install-exec install-exec-am install-html \ + install-html-am install-info install-info-am install-man \ + install-pdf install-pdf-am install-ps install-ps-am \ + install-strip installcheck installcheck-am installdirs \ + maintainer-clean maintainer-clean-generic mostlyclean \ + mostlyclean-generic mostlyclean-libtool pdf pdf-am ps ps-am \ + tags-am uninstall uninstall-am + +.PRECIOUS: Makefile + + +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/devel-docs/performance-logs/dashboard-add-marker.png b/devel-docs/performance-logs/dashboard-add-marker.png new file mode 100644 index 0000000..5d3d3ae Binary files /dev/null and b/devel-docs/performance-logs/dashboard-add-marker.png differ diff --git a/devel-docs/performance-logs/dashboard-start-recording.png b/devel-docs/performance-logs/dashboard-start-recording.png new file mode 100644 index 0000000..5cc719c Binary files /dev/null and b/devel-docs/performance-logs/dashboard-start-recording.png differ diff --git a/devel-docs/performance-logs/dashboard-stop-recording.png b/devel-docs/performance-logs/dashboard-stop-recording.png new file mode 100644 index 0000000..ffe3227 Binary files /dev/null and b/devel-docs/performance-logs/dashboard-stop-recording.png differ diff --git a/devel-docs/performance-logs/new-performance-issue.png b/devel-docs/performance-logs/new-performance-issue.png new file mode 100644 index 0000000..1206002 Binary files /dev/null and b/devel-docs/performance-logs/new-performance-issue.png differ diff --git a/devel-docs/performance-logs/performance-log-parameters.png b/devel-docs/performance-logs/performance-log-parameters.png new file mode 100644 index 0000000..33a0ec2 Binary files /dev/null and b/devel-docs/performance-logs/performance-log-parameters.png differ diff --git a/devel-docs/performance-logs/performance-log-viewer.png b/devel-docs/performance-logs/performance-log-viewer.png new file mode 100644 index 0000000..e90372d Binary files /dev/null and b/devel-docs/performance-logs/performance-log-viewer.png differ diff --git a/devel-docs/performance-logs/performance-logs.md b/devel-docs/performance-logs/performance-logs.md new file mode 100644 index 0000000..86e0746 --- /dev/null +++ b/devel-docs/performance-logs/performance-logs.md @@ -0,0 +1,651 @@ +# Performance Logs + +GIMP 2.10.8 and above has the ability to record *performance logs* containing +detailed information about the run-time behavior of the program, helping +locating and analyzing performance bottlenecks. + +This document describes how to record and view performance logs, and how to +report performance-related issues. + +## Table of Contents + + - [1. Recording Performance Logs](#1-recording-performance-logs) + - [1.1. Event Markers](#11-event-markers) + - [1.2. Log Parameters](#12-log-parameters) + - [2. Reporting Performance-Related Issues](#2-reporting-performance-related-issues) + - [3. What Information is Contained in the Log?](#3-what-information-is-contained-in-the-log) + - [4. Viewing Performance Logs](#4-viewing-performance-logs) + - [4.1. Sample-Selection Area](#41-sample-selection-area) + - [4.1.1. Selecting Samples](#411-selecting-samples) + - [4.2. Information Area](#42-information-area) + - [4.2.1. Information Page](#421-information-page) + - [4.2.2. Markers Page](#422-markers-page) + - [4.2.3. Variables Page](#423-variables-page) + - [4.2.4. Backtrace Page](#424-backtrace-page) + - [4.2.4.1. Threads Pane](#4241-threads-pane) + - [4.2.4.2. Stack Pane](#4242-stack-pane) + - [4.2.5. Profile Page](#425-profile-page) + - [4.2.5.1. Root Column](#4251-root-column) + - [4.2.5.1.1. Thread Filter](#42511-thread-filter) + - [4.2.5.1.2. Call-Graph Direction](#42512-call-graph-direction) + - [4.2.5.2. Function Columns](#4252-function-columns) + - [4.2.5.3. Source Columns](#4253-source-columns) + - [4.3. Selection Modifiers](#43-selection-modifiers) + - [4.3.1. Searching Samples](#431-searching-samples) + - [4.4. History Navigation](#44-history-navigation) + - [4.5. Environment Variables](#45-environment-variables) + +## 1. Recording Performance Logs + +Performance logs track the program state while the program is normally running. +In the usual case, you would record a performance log while performing a task +whose performance you wish to optimize, or against which you wish to report a +performance-related bug. +The recorded log can then be used to investigate the run-time behavior of the +program during the execution of the task. + +![Start recording a performance log](dashboard-start-recording.png) + +To record a performance log, open the *Dashboard* dockable (*Windows ▸ +Dockable Dialogs ▸ Dashboard*), click the *Record* button at the +bottom of the dockable, and select a filename for the log. +The *Record* button will subsequently change its color, indicating that the log +is being recorded. + +At this point, you should perform the task of interest as you normally would, +while state information is being recorded. +The log contains periodic samples of the program state during execution, and it +is therefore important to keep performing the task long enough (possibly +repeating it multiple times) so that a sufficiently large number of samples is +collected. +30 seconds or more is a good amount of time (longer periods improve the quality +of the log, while increasing its size). + +![Stop recording a performance log](dashboard-stop-recording.png) + +When you're done performing the task, stop recording the log by pressing the +*Record* button again. +At this point, GIMP will perform any necessary final steps, which may take a +while (usually, no more than a few seconds). +At the end of this process, the log is ready. + +*Note:* +In situations where you can't cleanly stop recording the log, such as +when GIMP crashes or freezes in the middle of the process, make sure to record +a *progressive* log, as described in [section *1.2*](#12-log-parameters). + +### 1.1. Event Markers + +When the recorded task is made up of multiple steps, it is useful to have an +indication of where the different steps begin and end within the log. +This is achieved using *event markers*. +An event marker is an annotated time-point in the log, signifying the +occurrence of an event of interest, such as the beginning or end of a logical +step. +It is up to you to add event markers to the log, as you see necessary. + +![Add an event marker to a performance log](dashboard-add-marker.png) + +To add an event marker, click the *Add Marker* button at the bottom of the +Dashboard dockable, next to the *Record* button, and enter a short description +for the corresponding event. +(Note that the *Add Marker* button is only available while a log is being +recorded.) +You may also click the button while holding the *Shift* key, to add an *empty* +event marker, not containing a description; this is useful when event markers +are needed to be added quickly. + +Event markers are numbered sequentially, and may be referred to by their +number (this is especially useful for empty event markers.) +The number of the next event marker (the one that will be added when the button +is clicked) is displayed on the *Add Marker* button. + +### 1.2. Log Parameters + +When creating a performance log, several parameters can be set at the bottom of +the file-selection dialog. +There should normally be no reason to change the parameters, unless noted +otherwise. + +![Performance-log parameters](performance-log-parameters.png) + + - *Sample Frequency:* + The number of program-state samples per second. + Higher values improve the resolution of the log, while making the recording + itself more expensive. + + - *Backtrace:* + Whether or not to include backtraces in the log. + Backtraces capture the code-paths taken while recording the log, and should + normally be included. + + - *Messages:* + Whether or not to include diagnostic messages in the log. + Diagnostic messages indicate errors and unexpected conditions, and should + normally be included. + + - *Progressive:* + Whether or not to record a progressive log. + + GIMP normally defers certain information to the end of the log, in order to + minimize the cost of recording. + If the log can't be cleanly finished—for example, if GIMP crashes or + freezes while recording the log—this information will be missing, rendering + the log of limited use. + In situations like these, a progressive log should be recorded; progressive + logs include all relevant information at each sample, allowing them to be + terminated at any time. + + Progressive logs may incur a higher overhead while recording. + +## 2. Reporting Performance-Related Issues + +![Reporting a performance-related issue](new-performance-issue.png) + +When reporting a performance-related issue, use the +[*performance* template][new-performance-issue] in GIMP's GitLab issue +tracker. +Provide a detailed description of the task you were performing, and attach a +performance log. +If the performance log is too big, attach a compressed version. +If you've added any empty event markers to the log, provide a description for +these markers in the report. + +Note that the log alone, while containing plenty of low-level information, +doesn't in itself explain *what* you were doing, nor does it contain all the +relevant details, so please *do* take time to describe the issue in addition to +the log. +Attaching a screencast of the process, possibly *while* recording the log, can +also be very helpful. + +## 3. What Information is Contained in the Log? + +The log consists mainly of a series of periodic *samples* of the program state. +(The default sampling rate is 10 samples per second; see +[section *1.2*](#12-log-parameters) for a way to modify this value.) +Each sample contains the values of all the *instrumentation variables* +displayed in the Dashboard. +Additionally, on supported platforms, each sample contains a full *program +backtrace*. +(Backtraces are currently supported on Linux and Windows; their level of detail +might depend on the available libraries and build-time options.) +When debugging information is available, corresponding source-location +information is included. + +Additionally, the log contains certain global information, not related to any +sample. +This includes GIMP version information, performance-log parameters (such as the +sampling rate), GEGL configuration parameters (such as the tile size), and the +values of all environment variables starting with `GIMP_`, `GEGL_`, or `BABL_`. + +## 4. Viewing Performance Logs + +![Performance-log viewer](performance-log-viewer.png) + +The GIMP source tree includes a graphical viewer for performance logs, under +the `tools/` directory. +The viewer is not included as part of GIMP installations, but is distributed as +part of source tarballs. + +To view a performance log, run: + + $GIMP_SRC_DIR/tools/performance-log-viewer $LOG_FILE + +where `$GIMP_SRC_DIR` is the root of the GIMP source tree, and `$LOG_FILE` is +the log filename. + +Note that there is no need to build or install GIMP in order to use the log +viewer. +Indeed, only the files prefixed with `performance-log` in the `tools/` +directory are actually needed. +The log viewer does require, however, a POSIX-compatible shell, Python 3, +PyGObject, and GTK+ 3 (including gir bindings). + +The rest of this section describes how to use the log viewer. + +### 4.1. Sample-Selection Area + +The upper part of the viewer window is the *sample-selection area*. +It consists of one or more graphs, visualizing a selected subset of the +instrumentation variables at each sample. +A variable list to the left of each graph is used to select the set of +variables to be visualized. +The list is searchable by variable name, and its tooltip shows the variable +descriptions. +A row buttons below the list allows adding, removing, and reordering the +graphs. + +Note that all variables visualized by the same graph share the same scale. +It therefore makes sense to visualize variables that measure related +quantities, such as `cache-occupied` and `swap-occupied`, using a single graph, +while visualizing variables that measure unrelated quantities, such as +`cache-occupied` and `cpu-usage`, using separate graphs. +Boolean variables, such as `cpu-active`, are an exception, and always use the +full height of the graph, regardless of the other variables they are visualized +along. + +A dashed line in a graph indicates that the corresponding variable's value is +infinite. +A missing line in part of the graph indicates that a measurement of the +corresponding variable is not available at the corresponding samples. + +Event markers are displayed as ticks above the graphs, at the nearest sample. + +Hovering over the sample-selection area displays a tooltip, showing the current +sample index, the time at which it was taken relative to the start of the log, +the values of all visualized variables at the current sample, and the +descriptions for all event markers corresponding to the current sample, if any. + +#### 4.1.1. Selecting Samples + +In addition to visualizing the instrumentation variables, the sample-selection +area is used to select a subset of the samples, referred to as the current +*selection*, which affects the data displayed in the information area, +described below. +The samples included in the current selection are highlighted on the graphs, +and a textual description of the current selection appears in the window's +titlebar. + +A single sample can be selected by clicking any of the graphs at the +corresponding area. +Multiple samples can be selected by clicking and dragging. +Entire spans of samples enclosed between a pair of event markers can be +selected by double-clicking, or double-clicking and dragging. +*Shift*, *Ctrl*, and *Shift+Ctrl* can be used as modifiers in order to +add-to, subtract-from, and intersect-with the current selection, respectively. + +Samples can also be selected using the keyboard, with the arrow, *Home*/*End*, +and *Shift* keys, while any of the graphs has focus. + +Right-clicking on any of the graphs, or pressing *Escape* while they have +focus, clears the selection. +The behavior when the selection is empty is equivalent to selecting all +samples. + +*Ctrl*-right-clicking on any of the graphs inverts the selection. + +### 4.2. Information Area + +The lower part of the viewer window is the *information area*. +It consists of multiple *pages* showing different data, generally relating to +the current selection of samples. + +#### 4.2.1. Information Page + +The *information page* shows global information contained in the log, not +associated with any sample, including: + + - *Log Parameters*: + Various parameters relating to the performance log itself. + See [section *1.2*](#12-log-parameters) for more information. + + - *GIMP Version*: + Verbose GIMP version information, as reported by `gimp -v`. + + - *Environment*: + A list of environment variables for the GIMP process recording the log, + starting with `GIMP_`, `GEGL_`, or `BABL_`. + These environment variables directly affect the behavior of GIMP. + + - *GEGL Config*: + A list of all the properties of the `GeglConfig` object of the GIMP process + recording the log. + +The key/value lists are searchable by key name. + +#### 4.2.2. Markers Page + +The *markers page* lists the event markers contained in the log, displaying +their number, relative time, and description. +It is only present in logs containing event markers. + +If the current selection contains samples corresponding to any markers, the +markers are selected in the markers-page list. Conversely, if any markers are +selected in the markers-page list, the corresponding samples are selected. + +#### 4.2.3. Variables Page + +The *variables page* shows instrumentation-variable statistics for the current +selection. + +When a single sample is selected, the current values of all variables are +listed, both in a formatted form, and in raw form as appears in the log file. +The formatted form is usually more convenient, while the raw form is more +precise. + +When multiple samples are selected, a number of statistics are listed for each +variables, taken over the selected set of samples. +This includes the minimum, maximum, and median values, the mean, and the +standard deviation. + +The variable list is searchable by variable name, and its tooltip shows the +variable descriptions. + +#### 4.2.4. Backtrace Page + +The *backtrace page* shows the program backtrace at the current sample. +It is only available when a single sample is selected, in logs containing +backtraces. + +##### 4.2.4.1. Threads Pane + +The *threads pane*, on the left side of the page, lists all active threads at +the time of the sample, displaying the following information: + + - *ID*: + The operating-system numeric thread-ID, uniquely identifying the thread. + + - *Name*: + The descriptive thread name. + Note that not all threads may be named, or the name may not be available on + some platforms. + + - *State*: + The thread's state. + May be one of: + + - *`R`*: + The thread is in a *running* state, executing code on the CPU. + + - *`S`*: + The thread is in a *sleeping* state, not executing any code. + This may include various types of non-running states on different + platforms. + + Note that on some platforms, thread state information may not be fully + accurate. + +The thread list is searchable by thread name. + +Double-clicking on a thread selects all samples at which the thread is in the +running state. + +##### 4.2.4.2. Stack Pane + +The *stack pane*, on the right side of the page, shows the selected thread's +call stack at the time of the sample, displaying the following information: + + - *Frame Number (#)*: + The stack-frame's nesting level, where 0 is the most-nested frame. + + - *Address*: + The start address of the function. + + - *Object*: + The object file containing the function. + The full path is available in the corresponding tooltip. + + - *Function*: + The function name. + + - *Offset*: + The offset of the current instruction, relative to the start of the + function. + + - *Source*: + The source file corresponding to the current instruction. + The full path is available in the corresponding tooltip. + + - *Line*: + The line number corresponding to the current instruction. + +Note that for some frames, only partial information may be available. + +When the source file for a given frame is found locally, a *file* icon is shown +at the end of the corresponding row. +The icon's tooltip shows the local path to the source file, and clicking on the +icon opens the file in a text editor, at the corresponding line (when +possible). +See [section *4.5*](#45-environment-variables) for information regarding how to +control local source-file lookup and the selected text editor. + +The frame list is searchable by function name. + +Double-clicking on a frame selects all samples at which the corresponding +function is present in the backtrace. + +#### 4.2.5. Profile Page + +The *profile page* shows a fully context-sensitive *call graph*, annotated with +frequency information, for the current selection. +It replaces the backtrace page when multiple samples are selected, in logs +containing backtraces. + +The call graph is comprised of all the call stacks at the selected samples. +Note that each sample generally includes multiple call stacks—one per each +thread. +Some call stacks may be filtered out, as described below. + +The call graph is traversed using a series of cascading columns (aka *Miller +columns*). +Each non-root column lists the direct *descendants* (*callers* or *callees*) of +a given function; selecting a descendant opens a new column to the right of the +current column, showing the descendants of the selected function, and so on. + +##### 4.2.5.1. Root Column + +The *root column* of the call graph shows a list of all functions included in +the graph. +The following frequency statistics are shown next to each function: + + - *Self*: + The number of call stacks in which the function appears at the most-nested + frame (when the graph direction is *caller → callee*), or at the + least-nested frame (when the graph direction is *callee → caller*), as a + percentage of the total number of call stacks. + When the graph direction is *caller → callee*, this quantity indicates the + relative amount of time spent executing code belonging exclusively to this + function. + + - *All*: + The number of call stacks in which the function appears at any frame, as a + percentage of the total number of call stacks. + This quantity indicates the relative amount of time spent executing code + belonging to this function, or any of its (direct or indirect) descendant, + and is always greater-than or equal-to *Self*. + +By default, the list is sorted by *All*, but it can be sorted by *Self* or by +function name as well. +The list is searchable by function name. +Pressing *Escape* while the list has focus deselects the current item. + +The root-column header buttons allow controlling the structure of the call +graph: + +###### 4.2.5.1.1. Thread Filter + +The *Threads* button opens the *thread filter*, allowing control over which +threads, and which states of each thread, are included in the graph. + +The thread filter lists all threads included in the current selection. +Each thread is identified by ID and name, as described in +[section *4.2.4.1*](#4241-threads-pane). +Next to each thread is a row of toggles, corresponding to the different thread +states; only call stacks during which the thread was in one of the active +states are included in the graph. +Clicking on a thread-state column title toggles the entire column. + +The thread list can be searched by thread name. + +###### 4.2.5.1.2. Call-Graph Direction + +By default, the graph direction is *caller → callee*—the direct descendants of +each function are its callees. +The *Call-Graph Direction* button allows toggling the graph between the *caller +→ callee* direction, and the reverse *callee → caller* direction, in which the +direct descendants of each function are its callers. + +##### 4.2.5.2. Function Columns + +When a function from the root column is selected, a new *function column* opens +to the right of the root column, listing the direct descendants of the +function. +The descendants list has a similar structure to the function list of the root +column. +When a descendant function is selected, a subsequent function column opens to +the right of current column, showing its direct descendants, and so on. +In this manner, the call graph can be traversed according to its current +direction. + +Note that the call graph is fully *context-sensitive*. +This means that the listed descendants of the function depend on the current +column's path in the graph, that is, on the call chain leading to the column. + +For example, suppose functions `foo1` and `foo2` both call `bar`, which, in +turn, calls `baz1` and `baz2`; however, `bar` only calls `baz1` when called +through `foo1`, and `baz2` when called through `foo2`. +When selecting `foo1` in the root column, in the *caller → callee* direction, +and subsequently selecting `bar` in `foo1`'s column, `bar`'s column will only +list `baz1` as a descendant, since `baz2` is never called by `bar` when it is +called through `foo1`. +Likewise, when selecting `foo2` in the root column, and `bar` in `foo2`'s +column, only `baz2` will be listed in `bar`'s column. + +Context-sensitivity extends to the frequency statistics as well: +The only call stacks considered for each descendant are those in which it +appears as part of a call chain matching the current column. +In other words, the statistics are local to the current call chain, and are +generally different from the global statistics for the same functions. + +In addition to the function's callees or callers, the descendants list includes +a special *[Self]* item, corresponding to the current function. +It is most useful for its *Self* percentage, which, in the *caller → callee* +direction, indicates the amount of time spent executing code belonging +exclusively to the current function, and not to any of its descendants, +relative to the total amount of time spent executing the function as a whole. +In other words, in non-recursive cases, the sum of *[Self]*'s *Self* +percentage, and the rest of the descendants' *All* percentage, adds up to +100%—the full execution time of the function. + +Double-clicking on any of the descendants selects the corresponding function in +the root column, effectively discarding the current call-chain context. +It is especially useful before swapping the graph's direction. + +The *Select Samples* button in the column header selects all the samples +corresponding to the current column, that is, all the samples whose call stacks +contribute to column. +The button's tooltip shows a textual description of the samples. + +##### 4.2.5.3. Source Columns + +When the *[Self]* item of a function column is selected, if the log contains +source-location information for the function, and the corresponding source file +is found locally, a new *source column* opens to the right of the function +column, showing the source code for the function. +Source lines which appear as part of call stacks display similar frequency +statistics to the root- and function-columns, and are referred to as *annotated +lines*. +Similarly to descendants in function columns, annotated lines are also +context-sensitive. + +When a source column is opened, the annotated line with the highest *All* +percentage is selected. +The *Previous Annotated Line* and *Next Annotated Line* buttons on the left +side of the column header can be used to quickly navigate between annotated +lines. +The source code is searchable by line number. + +The *Select Samples* button in the column header selects all the samples +corresponding to the selected annotated source line. +The button's tooltip shows a textual description of the samples. + +The file button in the column header opens the source file in a text editor, at +the selected line, if possible (see +[section *4.5*](#45-environment-variables)). +The button's tooltip shows the full path to the file. + +### 4.3. Selection Modifiers + +The buttons on the right side of the window's titlebar allow modifying the +selection in various ways: +The *Clear Selection* and *Invert Selection* buttons clear and invert the +selection, respectively. +The *Find Samples* button allows searching for samples, as explained below. + +#### 4.3.1. Searching Samples + +The *Find Samples* button opens a popover allowing searching for all samples +matching a user-defined condition. +The condition should be a Python expression, evaluating to a boolean value. +The selected samples are those for which the expression evaluates to `True`. + +A number of sample-dependent variables and functions are provided: + + - *Instrumentation Variables*: + All instrumentation variables are available as variables of type `float`. + Hyphens in variable names are replaced with underscores. + + For example, the expression `cpu_usage > 0.5` matches all samples at which + the `cpu-usage` variable is greater-than or equal-to 0.5, that is, at which + CPU usage is above 50%. + + - *`thread (id, state = None)`*: + The `thread()` function matches all samples whose backtrace contains a + given thread. + + The `id` argument may be either a thread-ID of type `int`, or a thread name + of type `str`. + The argument may be a regular expression, which should fully match the + thread name. + + The optional `state` argument, if not `None`, may specify a thread state + (see [section *4.2.4.1*](#4241-threads-pane)). + Only samples at which the thread is in the given state are matched. + The argument may be a regular expression, which should fully match the + thread state. + + For example, the expression `thread ('paint', 'R')` matches all samples at + which the `paint` thread is in the `R` (*running*) state. + + - *`function (name, id = None, state = None)`*: + The `function()` function matches all samples whose backtrace contains a + given function. + + The `name` argument should specify a function name. + The argument may be a regular expression, which should fully match the + function name. + + The optional `id` and `state` arguments have similar meaning to the + corresponding arguments of the `thread()` function, and may be used to + limit the search to the call stacks of matching threads. + + For example, the expression `function ('gimp_image_.*')` matches all + samples whose backtrace includes a function beginning with `gimp_image_`, + that is, one of the `GimpImage` functions. + +By default, the matching samples replace the current selection, but they can be +set to *add-to*, *subtract-from*, or *intersect-with* the current selection +instead. + +### 4.4. History Navigation + +The *Back* and *Forward* buttons on the left side of the window's titlebar +allow moving backward and forward in the viewer's state history. +The viewer state consists of the current selection, and the current call-graph +direction, thread filter, and path. + +### 4.5. Environment Variables + +The following environment variables are used by the viewer: + + - *`PERFORMANCE_LOG_VIEWER_PATH`*: + Colon-separated list of paths, under which to look for local source files. + If the variable is not defined, the current directory is used instead. + + Source files appearing in the log are searched as follows, where the first + matching file is selected: + + - If the path is absolute, look for the file at the exact location. + + - For each local path in `PERFORMANCE_LOG_VIEWER_PATH`, try concatenating + the local path and the log path. + If no such file exists, remove the first component of log path, and try + again. + + - *`PERFORMANCE_LOG_VIEWER_EDITOR`*: + The command to use to launch the text editor. + The special strings `{file}` and `{line}` are replaced with the filename + and line number, respectively. + If the variable is not defined, a default text editor is used. + +[new-performance-issue]: https://gitlab.gnome.org/GNOME/gimp/issues/new?issuable_template=performance -- cgit v1.2.3