bug#75004: 30.0.92; documentation unclear about D-Bus support

bug#75004: 30.0.92; documentation unclear about D-Bus support

[Mike Kupfer]

I would like to use TRAMP to access the files on my Android phone.  It's
not working.  While trying to troubleshoot, I am finding the
documentation less than clear in a couple places, so I'm reporting those
shortcomings here.

1. The TRAMP "GVFS-based external methods" page says

  Emacs must have the message bus system, D-Bus integration active, see
  D-Bus(dbus).

I do not understand what it means for D-Bus integration to be "active".
Is it a runtime thing, or is it just talking about whether the code is
compiled in?  Is there a command to run, a variable to look at, or an
sexp to evaluate that would tell me whether D-Bus integration is
"active"?  I looked in the D-Bus Info documentation and wasn't able to
find any clues there.  Nor did a web search help.

2. The "D-Bus integration in Emacs" Info file just covers the API.  But
it assumes that you have D-Bus support compiled in.  I think there
should be some mention that D-Bus support is a compile-time option.  I
also would like to see instructions for how to tell if the necessary
code was, in fact, compiled in.  (The *Gnus* documentation says it's
(featurep 'dbusbind).  That's not the place users will look.)

In GNU Emacs 30.0.92 (build 1, x86_64-pc-linux-gnu, X toolkit, cairo
 version 1.16.0, Xaw scroll bars) of 2024-10-28 built on alto
Windowing system distributor 'The X.Org Foundation', version 11.0.12101007
System Description: Debian GNU/Linux 12 (bookworm)

Configured using:
 'configure --prefix=/usr/local --with-native-compilation=no'

Configured features:
CAIRO FREETYPE GIF GLIB GMP GNUTLS GSETTINGS HARFBUZZ JPEG LIBSELINUX
LIBXML2 MODULES NOTIFY INOTIFY PDUMPER PNG SECCOMP SOUND THREADS TIFF
TOOLKIT_SCROLL_BARS WEBP X11 XDBE XIM XPM LUCID ZLIB

Important settings:
  value of $LC_TIME: C
  value of $LANG: en_US.UTF-8
  value of $XMODIFIERS: @im=ibus
  locale-coding-system: utf-8-unix

Major mode: Info

Minor modes in effect:
  server-mode: t
  delete-selection-mode: t
  display-time-mode: t
  global-eldoc-mode: t
  show-paren-mode: t
  mouse-wheel-mode: t
  file-name-shadow-mode: t
  isearch-fold-quotes-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  minibuffer-regexp-mode: t
  buffer-read-only: t
  indent-tabs-mode: t
  transient-mark-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t

Load-path shadows:
None found.

Features:
(shadow mh-identity emacsbug bug-reference texinfo texinfo-loaddefs
tabify man info apropos sort gnus-async gnus-bcklg gnus-kill gnus-ml
disp-table timezone network-stream url-http url-gw nsm url-cache
url-auth url-handlers nnrss nndoc nndraft nnnil gnus-agent gnus-srvr
nnvirtual nntp gnus-cache pcmpl-unix cl-print tramp-androidsu tramp-adb
tramp-archive tramp-cmds tramp-container tramp-ftp help-fns radix-tree
tramp-gvfs tramp-cache time-stamp tramp-sh tramp trampver
tramp-integration tramp-message tramp-compat tramp-loaddefs view crm
mh-alias org-clock grep compile vc-hg diff-mode track-changes easy-mmode
cal-move diary-lib diary-loaddefs cal-iso misearch multi-isearch
oc-basic ol-eww eww url-queue mm-url ol-rmail ol-mhe ol-irc ol-info
ol-gnus nnselect ol-docview doc-view filenotify jka-compr image-mode
exif ol-bibtex bibtex ol-bbdb ol-w3m ol-doi org-link-doi cl-extra
help-mode face-remap org-agenda org-element org-persist xdg org-id
org-element-ast inline avl-tree generator org-refile org ob ob-tangle
ob-ref ob-lob ob-table ob-exp org-macro org-src sh-script smie treesit
executable ob-comint org-pcomplete org-list org-footnote org-faces
org-entities org-version ob-emacs-lisp ob-core ob-eval org-cycle
org-table ol rx org-fold org-fold-core org-keys oc org-loaddefs
find-func cal-menu calendar cal-loaddefs org-compat org-macs format-spec
dired-aux dired-x textsec uni-scripts idna-mapping ucs-normalize
uni-confusable textsec-check shr-color color qp mail-extr smiley
mm-archive pp mh-search mh-letter mh-show goto-addr thingatpt gnus-cite
mh-mime mule-util mh-thread mh-inc hl-line mh-tool-bar mh-acros mh-seq
mh-xface mh-utils mh-folder which-func imenu files-x mdk-mail gnus-mh
gnus-msg mh-comp mh-scan mh-gnus gnus-dup nnmh gnus-score score-mode
gnus-art mm-uu mml2015 mm-view mml-smime smime gnutls dig gnus-sum shr
pixel-fill kinsoku url-file svg dom gnus-group gnus-undo gnus-start
gnus-dbus dbus xml gnus-cloud nnimap nnmail browse-url url url-proxy
url-privacy url-expand url-methods url-history url-cookie
generate-lisp-file url-domsuf url-util url-parse auth-source cl-seq
eieio eieio-core cl-macs json map byte-opt gv bytecomp byte-compile
url-vars mail-source utf7 nnoo parse-time iso8601 gnus-spec gnus-int
gnus-range gnus-win gnus nnheader range wid-edit mh-e mh-buffers
mh-loaddefs message sendmail mailcap yank-media puny dired
dired-loaddefs rfc822 mml mml-sec password-cache epa derived epg rfc6068
epg-config gnus-util text-property-search time-date mm-decode mm-bodies
mm-encode mail-parse rfc2231 rfc2047 rfc2045 mm-util ietf-drums
mail-prsvr mailabbrev mail-utils gmm-utils mailheader server timeclock
noutline outline icons cc-mode cc-fonts cc-guess cc-menus cc-cmds
cc-styles cc-align cc-engine cc-vars cc-defs advice shell pcomplete
comint subr-x ansi-osc ansi-color ring xcscope delsel time vc
cl-loaddefs cl-lib vc-dispatcher mdk-hacks rmc iso-transl tooltip cconv
eldoc paren electric uniquify ediff-hook vc-hooks lisp-float-type
elisp-mode mwheel term/x-win x-win term/common-win x-dnd touch-screen
tool-bar dnd fontset image regexp-opt fringe tabulated-list replace
newcomment text-mode lisp-mode prog-mode register page tab-bar menu-bar
rfn-eshadow isearch easymenu timer select scroll-bar mouse jit-lock
font-lock syntax font-core term/tty-colors frame minibuffer nadvice seq
simple cl-generic indonesian philippine cham georgian utf-8-lang
misc-lang vietnamese tibetan thai tai-viet lao korean japanese eucjp-ms
cp51932 hebrew greek romanian slovak czech european ethiopic indian
cyrillic chinese composite emoji-zwj charscript charprop case-table
epa-hook jka-cmpr-hook help abbrev obarray oclosure cl-preloaded button
loaddefs theme-loaddefs faces cus-face macroexp files window
text-properties overlay sha1 md5 base64 format env code-pages mule
custom widget keymap hashtable-print-readable backquote threads inotify
dynamic-setting system-font-setting font-render-setting cairo x-toolkit
x multi-tty move-toolbar make-network-process emacs)

Memory information:
((conses 16 636507 146821) (symbols 48 36779 9)
 (strings 32 146543 17478) (string-bytes 1 4855597) (vectors 16 96383)
 (vector-slots 8 1864368 116321) (floats 8 670 9602)
 (intervals 56 25189 271) (buffers 984 92))

bug#75004: 30.0.92; documentation unclear about D-Bus support

[Michael Albinus via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Mike Kupfer <kupfer@rawbw.com> writes:

Hi Mike,

> I would like to use TRAMP to access the files on my Android phone.  It's
> not working.  While trying to troubleshoot, I am finding the
> documentation less than clear in a couple places, so I'm reporting those
> shortcomings here.

Thanks for the report! Writing documentation is always hard in order to
determine what you can assume from the reader.

Could you pls check, whether the appended patch (for dbus.texi and
tramp.texi) helps?

> In GNU Emacs 30.0.92 (build 1, x86_64-pc-linux-gnu, X toolkit, cairo
>  version 1.16.0, Xaw scroll bars) of 2024-10-28 built on alto
> Windowing system distributor 'The X.Org Foundation', version 11.0.12101007
> System Description: Debian GNU/Linux 12 (bookworm)
>
> Configured using:
>  'configure --prefix=/usr/local --with-native-compilation=no'
>
> Configured features:
> CAIRO FREETYPE GIF GLIB GMP GNUTLS GSETTINGS HARFBUZZ JPEG LIBSELINUX
> LIBXML2 MODULES NOTIFY INOTIFY PDUMPER PNG SECCOMP SOUND THREADS TIFF
> TOOLKIT_SCROLL_BARS WEBP X11 XDBE XIM XPM LUCID ZLIB

Hmm, DBUS is not mentioned. Per default, it should be enabled. Perhaps
you need to install the libdbus-1-dev package on your Debian system?

Best regards, Michael.

bug#75004: 30.0.92; documentation unclear about D-Bus support

[Michael Albinus via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[-- Attachment #1: Type: text/plain, Size: 23 bytes --]

And here's the patch.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Type: text/x-patch, Size: 1773 bytes --]

diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi
index 4d46564944f..1020e027774 100644
--- a/doc/misc/dbus.texi
+++ b/doc/misc/dbus.texi
@@ -75,9 +75,12 @@ Overview
 @cindex overview

 D-Bus is an inter-process communication mechanism for applications
-residing on the same host.  The communication is based on
-@dfn{messages}.  Data in the messages is carried in a structured way,
-it is not just a byte stream.
+residing on the same host.  Emacs uses it when it is compiled with the
+respective library, see configuration option @option{--with-dbus}.  At
+runtime, the form @code{(featurep 'dbusbind)} indicates D-Bus support.
+
+D-Bus communication is based on @dfn{messages}.  Data in the messages is
+carried in a structured way, it is not just a byte stream.

 The communication is connection oriented to two kinds of message
 buses: a so called @dfn{system bus}, and a @dfn{session bus}.  On a
diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi
index 94e06ce6af3..b98b9b1fe5c 100644
--- a/doc/misc/tramp.texi
+++ b/doc/misc/tramp.texi
@@ -1365,9 +1365,12 @@ GVFS-based methods
 @acronym{GVFS} are mounted locally through @acronym{FUSE} and
 @value{tramp} uses this locally mounted directory internally.

-Emacs uses the D-Bus mechanism to communicate with @acronym{GVFS}@.
-Emacs must have the message bus system, D-Bus integration active,
-@pxref{Top, , D-Bus, dbus}.
+Emacs uses the D-Bus mechanism to communicate with @acronym{GVFS}@.  It
+must have been compiled with D-Bus support, @pxref{Top, , D-Bus, dbus}.
+
+@vindex tramp-gvfs-enabled
+The @code{tramp-gvfs-enabled} variable, being non-@code{nil}, signals
+that @value{tramp} can use @acronym{GVFS}-based methods.

 @table @asis
 @cindex method @option{afp}

bug#75004: 30.0.92; documentation unclear about D-Bus support

[Mike Kupfer]

Michael Albinus wrote:

> Could you pls check, whether the appended patch (for dbus.texi and
> tramp.texi) helps?

It does.  Thanks for the fast turnaround.

> > Configured features:
> > CAIRO FREETYPE GIF GLIB GMP GNUTLS GSETTINGS HARFBUZZ JPEG LIBSELINUX
> > LIBXML2 MODULES NOTIFY INOTIFY PDUMPER PNG SECCOMP SOUND THREADS TIFF
> > TOOLKIT_SCROLL_BARS WEBP X11 XDBE XIM XPM LUCID ZLIB
> 
> Hmm, DBUS is not mentioned. Per default, it should be enabled. Perhaps
> you need to install the libdbus-1-dev package on your Debian system?

Yes, that was the issue; thanks.

BTW, I was surprised that 'configure' did not error out when I supplied
--with-dbus (or --with-dbus=yes) on the command line.  I expect
'configure' to disable a feature (and exit with status 0) if the feature
can't be provided and wasn't explicitly requested, but I thought the
inability to provide a specifically requested feature was considered an
error.  Am I misunderstanding how 'configure' is supposed to work?

mike

bug#75004: 30.0.92; documentation unclear about D-Bus support

[Michael Albinus via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Mike Kupfer <kupfer@rawbw.com> writes:

Hi Mike,

>> Could you pls check, whether the appended patch (for dbus.texi and
>> tramp.texi) helps?
>
> It does.  Thanks for the fast turnaround.

Thanks for the feedback. Pushed to the emacs-30 branch.

> BTW, I was surprised that 'configure' did not error out when I supplied
> --with-dbus (or --with-dbus=yes) on the command line.  I expect
> 'configure' to disable a feature (and exit with status 0) if the feature
> can't be provided and wasn't explicitly requested, but I thought the
> inability to provide a specifically requested feature was considered an
> error.  Am I misunderstanding how 'configure' is supposed to work?

I'm not an expert in this department. Eli?

> mike

Best regards, Michael.

bug#75004: 30.0.92; documentation unclear about D-Bus support

[Eli Zaretskii]

> Cc: 75004@debbugs.gnu.org
> Date: Sun, 22 Dec 2024 09:42:23 +0100
> From:  Michael Albinus via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> Mike Kupfer <kupfer@rawbw.com> writes:
> 
> > BTW, I was surprised that 'configure' did not error out when I supplied
> > --with-dbus (or --with-dbus=yes) on the command line.  I expect
> > 'configure' to disable a feature (and exit with status 0) if the feature
> > can't be provided and wasn't explicitly requested, but I thought the
> > inability to provide a specifically requested feature was considered an
> > error.  Am I misunderstanding how 'configure' is supposed to work?
> 
> I'm not an expert in this department. Eli?

This is not magic, and needs to be explicitly coded in configure.ac.
The --with-dbus option doesn't have such code, and basically turns on
D-Bus support only if available; otherwise it silently turns it off.
If we want to have --with-dbus error out, we need to change the
default of --with-dbus to "ifavailable', since otherwise many people
who don't want D-Bus or don't have it installed (or build Emacs on
platforms where D-Bus is unavailable) will get errors where previously
they didn't.