See http://www.freedesktop.org/software/dbus/ for lots of documentation,
mailing lists, etc.
-See also the file HACKING for notes of interest to developers working on D-Bus.
+See also the file CONTRIBUTING.md for notes of interest to developers
+working on D-Bus.
If you're considering D-Bus for use in a project, you should be aware
that D-Bus was designed for a couple of specific use cases, a "system
only by accident; so you should evaluate carefully whether D-Bus makes
sense for your project.
+Security
+==
+
+If you find a security vulnerability that is not known to the public,
+please report it privately to dbus-security@lists.freedesktop.org
+or by reporting a freedesktop.org bug that is marked as
+restricted to the "D-BUS security group" (you might need to "Show
+Advanced Fields" to have that option).
+
+On Unix systems, the system bus (dbus-daemon --system) is designed
+to be a security boundary between users with different privileges.
+
+On Unix systems, the session bus (dbus-daemon --session) is designed
+to be used by a single user, and only accessible by that user.
+
+We do not currently consider D-Bus on Windows to be security-supported,
+and we do not recommend allowing untrusted users to access Windows
+D-Bus via TCP.
+
Note: low-level API vs. high-level binding APIs
===
dbus could be build by using autotools or cmake.
When using autotools the configure step is initiated by running ./configure
-with our without additional configuration flags.
+with or without additional configuration flags. dbus requires GNU Make
+(on BSD systems, this is typically called gmake) or a "make" implementation
+with compatible extensions.
When using cmake the configure step is initiated by running the cmake
-program with our without additional configuration flags.
+program with or without additional configuration flags.
Configuration flags
===
-When using autools the dbus-specific configuration flags that can be given to
-the ./configure program are these
-
- --enable-tests enable unit test code
- --enable-verbose-mode support verbose debug mode
- --enable-asserts include assertion checks
- --enable-checks include sanity checks on public API
- --enable-xml-docs build XML documentation (requires xmlto)
- --enable-doxygen-docs build DOXYGEN documentation (requires Doxygen)
- --enable-gcov compile with coverage profiling instrumentation (gcc only)
- --enable-abstract-sockets use abstract socket namespace (linux only)
- --enable-selinux build with SELinux support
- --enable-dnotify build with dnotify support (linux only)
- --enable-kqueue build with kqueue support (*BSD only)
- --with-xml=libxml/expat XML library to use
- --with-init-scripts=redhat Style of init scripts to install
- --with-session-socket-dir=dirname Where to put sockets for the per-login-session message bus
- --with-test-socket-dir=dirname Where to put sockets for make check
- --with-system-pid-file=pidfile PID file for systemwide daemon
- --with-system-socket=filename UNIX domain socket for systemwide daemon
- --with-console-auth-dir=dirname directory to check for console ownerhip
- --with-dbus-user=<user> User for running the DBUS daemon (messagebus)
- --with-gnu-ld assume the C compiler uses GNU ld [default=no]
- --with-tags[=TAGS] include additional configurations [automatic]
- --with-x use the X Window System
-
-When using the cmake build system the dbus-specific configuration flags that can be given
-to the cmake program are these (use -D<key>=<value> on command line)
-
- CMAKE_BUILD_TYPE set dbus build mode - one of Debug|Release|RelWithDebInfo|MinSizeRel
- DBUS_BUILD_TESTS enable unit test code default=ON
- DBUS_BUILD_X11 Build X11-dependent code default=ON
- HAVE_CONSOLE_OWNER_FILE enable console owner file (solaris only) ) default=ON
- DBUS_DISABLE_ASSERTS Disable assertion checking default=OFF
- DBUS_DISABLE_CHECKS Disable public API sanity checking default=OFF
- DBUS_ENABLE_ABSTRACT_SOCKETS enable support for abstract sockets (linux only) default=ON
- DBUS_ENABLE_ANSI enable -ansi -pedantic gcc flags default=OFF
- DBUS_ENABLE_DNOTIFY build with dnotify support (linux only) default=ON
- DBUS_ENABLE_VERBOSE_MODE support verbose debug mode default=ON
- DBUS_ENABLE_DOXYGEN_DOCS build DOXYGEN documentation (requires Doxygen) default=ON
- DBUS_GCOV_ENABLED compile with coverage profiling instrumentation (gcc only) default=OFF
- DBUS_INSTALL_SYSTEM_LIBS install required system libraries default (windows only) =OFF
- DBUS_USE_EXPAT Use expat (== ON) or libxml2 (==OFF) default=ON [1]
- DBUS_USE_NONCE_TCP_DEFAULT_ADDRESS Use nonce tcp default address default=OFF
- DBUS_USE_OUTPUT_DEBUG_STRING enable win32 debug port for message output default=OFF
-
- [1] requires installed development package of the related dependency
+When using autotools, run "./configure --help" to see the possible
+configuration options and environment variables.
+When using cmake, inspect README.cmake to see the possible
+configuration options and environment variables.
API/ABI Policy
===
main D-Bus package, and have their own release cycles, levels of
maturity, and ABI stability policies. Please consult the documentation
for your binding.
+
+Bootstrapping D-Bus on new platforms
+===
+
+A full build of D-Bus, with all regression tests enabled and run, has some
+dependencies which themselves depend on D-Bus, either for compilation or
+for some of *their* regression tests: GLib, dbus-glib and dbus-python are
+currently affected.
+
+To avoid circular dependencies, when bootstrapping D-Bus for the first time
+on a new OS or CPU architecture, you can either cross-compile some of
+those components, or choose the build order and options carefully:
+
+* build and install D-Bus without tests
+ - do not use the --enable-modular-tests=yes configure option
+ - do not use the --enable-tests=yes configure option
+* build and install GLib, again without tests
+* use those versions of libdbus and GLib to build and install dbus-glib
+* ... and use those to install dbus-python
+* rebuild libdbus; this time you can run all of the tests
+* rebuild GLib; this time you can run all of the tests