[RFA/doco] Document the GDB python directory.

[RFA/doco] Document the GDB python directory.

[Joel Brobecker]

Hello,

The following patch add NEWS & documentation for the new python directory:

    http://www.sourceware.org/ml/gdb-patches/2010-06/msg00565.html

2010-06-27  Joel Brobecker  <brobecker@adacore.com>

        * NEWS: Add entry announcing the python directory.

2010-06-27  Joel Brobecker  <brobecker@adacore.com>

        * gdb.texinfo (Python): Document what the python directory is
        and what its location is.
        (Basic Python): Document the gdb.PYTHONDIR constant.

OK to commit?

Thanks,
-- 
Joel

---
 gdb/NEWS            |    5 +++++
 gdb/doc/gdb.texinfo |   12 ++++++++++++
 2 files changed, 17 insertions(+), 0 deletions(-)

diff --git a/gdb/NEWS b/gdb/NEWS
index 1e1ea39..3b64088 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -103,6 +103,11 @@ is now deprecated.
 
 * Python scripting
 
+** GDB now provides a new directory location, called the python directory,
+   where Python scripts written for GDB can be installed.  The location
+   of that directory is <data-directory>/python, where <data-directory>
+   is the GDB data directory.
+
 ** The GDB Python API now has access to breakpoints, symbols, symbol
    tables, program spaces, and frame's code blocks.  Additionally, GDB
    Parameters can now be created from the API, and manipulated via
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index cbd636f..d0e5a39 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -20089,6 +20089,13 @@ You can script @value{GDBN} using the @uref{http://www.python.org/,
 Python programming language}.  This feature is available only if
 @value{GDBN} was configured using @option{--with-python}.
 
+@cindex python directory
+Python scripts used by @value{GDBN} should be installed in
+@file{@var{data-directory}/python}, where @var{data-directory} is
+the data directory as determined at @value{GDBN} startup (@pxref{Data Files}).  This directory, known as the @dfn{python directory},
+is automatically added to the Python Search Path in order to allow
+the Python interpreter to locate all scripts installed at this location.
+
 @menu
 * Python Commands::             Accessing Python from @value{GDBN}.
 * Python API::                  Accessing @value{GDBN} from Python.
@@ -20199,6 +20206,11 @@ methods and classes added by @value{GDBN} are placed in this module.
 @value{GDBN} automatically @code{import}s the @code{gdb} module for
 use in all scripts evaluated by the @code{python} command.
 
+@findex gdb.PYTHONDIR
+@defvar PYTHONDIR
+A string containing the python directory (@pxref{Python}).
+@end defvar
+
 @findex gdb.execute
 @defun execute command [from_tty]
 Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
-- 
1.7.1

Re: [RFA/doco] Document the GDB python directory.

[Eli Zaretskii]

> From: Joel Brobecker <brobecker@adacore.com>
> Cc: Joel Brobecker <brobecker@adacore.com>
> Date: Sun, 27 Jun 2010 11:14:46 -0700
> 
> 2010-06-27  Joel Brobecker  <brobecker@adacore.com>
> 
>         * NEWS: Add entry announcing the python directory.
> 
> 2010-06-27  Joel Brobecker  <brobecker@adacore.com>
> 
>         * gdb.texinfo (Python): Document what the python directory is
>         and what its location is.
>         (Basic Python): Document the gdb.PYTHONDIR constant.
> 
> OK to commit?

Yes, but please add to the NEWS entry a pointer to the section in the
manual where the details are.

Thanks.

Re: [RFA/doco] Document the GDB python directory.

[Joel Brobecker]

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

> Yes, but please add to the NEWS entry a pointer to the section in the
> manual where the details are.

Thanks. Would the following be the correct way of adding that reference
in the NEWS file?

Thanks,
-- 
Joel

[-- Attachment #2: pythondir-doco-2.diff --]
[-- Type: text/x-diff, Size: 2664 bytes --]

commit 919edacf2281a00e3900fbd92421be88e53445aa
Author: Joel Brobecker <brobecker@adacore.com>
Date:   Sun Jun 27 10:58:40 2010 -0700

    Document the GDB python directory.
    
    2010-06-27  Joel Brobecker  <brobecker@adacore.com>
    
            * NEWS: Add entry announcing the python directory.
    
    2010-06-27  Joel Brobecker  <brobecker@adacore.com>
    
            * gdb.texinfo (Python): Document what the python directory is
            and what its location is.
            (Basic Python): Document the gdb.PYTHONDIR constant.

diff --git a/gdb/NEWS b/gdb/NEWS
index 1e1ea39..9fa2af5 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -103,6 +103,12 @@ is now deprecated.
 
 * Python scripting
 
+** GDB now provides a new directory location, called the python directory,
+   where Python scripts written for GDB can be installed.  The location
+   of that directory is <data-directory>/python, where <data-directory>
+   is the GDB data directory.  For more details, see the `Debugging with
+   GDB' manual, section `Scripting GDB using Python'.
+
 ** The GDB Python API now has access to breakpoints, symbols, symbol
    tables, program spaces, and frame's code blocks.  Additionally, GDB
    Parameters can now be created from the API, and manipulated via
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index cbd636f..d0e5a39 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -20089,6 +20089,13 @@ You can script @value{GDBN} using the @uref{http://www.python.org/,
 Python programming language}.  This feature is available only if
 @value{GDBN} was configured using @option{--with-python}.
 
+@cindex python directory
+Python scripts used by @value{GDBN} should be installed in
+@file{@var{data-directory}/python}, where @var{data-directory} is
+the data directory as determined at @value{GDBN} startup (@pxref{Data Files}).  This directory, known as the @dfn{python directory},
+is automatically added to the Python Search Path in order to allow
+the Python interpreter to locate all scripts installed at this location.
+
 @menu
 * Python Commands::             Accessing Python from @value{GDBN}.
 * Python API::                  Accessing @value{GDBN} from Python.
@@ -20199,6 +20206,11 @@ methods and classes added by @value{GDBN} are placed in this module.
 @value{GDBN} automatically @code{import}s the @code{gdb} module for
 use in all scripts evaluated by the @code{python} command.
 
+@findex gdb.PYTHONDIR
+@defvar PYTHONDIR
+A string containing the python directory (@pxref{Python}).
+@end defvar
+
 @findex gdb.execute
 @defun execute command [from_tty]
 Evaluate @var{command}, a string, as a @value{GDBN} CLI command.

Re: [RFA/doco] Document the GDB python directory.

[Eli Zaretskii]

> Date: Mon, 28 Jun 2010 11:57:14 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: gdb-patches@sourceware.org
> 
> > Yes, but please add to the NEWS entry a pointer to the section in the
> > manual where the details are.
> 
> Thanks. Would the following be the correct way of adding that reference
> in the NEWS file?
> [...]
> +** GDB now provides a new directory location, called the python directory,
> +   where Python scripts written for GDB can be installed.  The location
> +   of that directory is <data-directory>/python, where <data-directory>
> +   is the GDB data directory.  For more details, see the `Debugging with
> +   GDB' manual, section `Scripting GDB using Python'.

It would be enough to say

  For more details, see section `Scripting GDB using Python' in the
  manual.

Thanks.

Re: [RFA/doco] Document the GDB python directory.

[Joel Brobecker]

> It would be enough to say
> 
>   For more details, see section `Scripting GDB using Python' in the
>   manual.

Ok - changed as suggested (thanks!), and checked in.

Thank you,
-- 
Joel