[RFA] New substitute-path commands

[RFA] New substitute-path commands

[Joel Brobecker]

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

Hello,

Following up on a discussing that took place on the gdb@ mailing list:

        http://sources.redhat.com/ml/gdb/2006-06/msg00192.html

I implemented a new set of commands that should be useful in the case
when a developer debugs a program of which the source tree has been
moved to a different location from where it was compiled.

The new commands are:

        (gdb) substitute-path add <from> <to>
        (gdb) substitute-path remove
        (gdb) substitute-path

  * "substitute-path add" adds a substitution rule, where the first
    instance of <from> is replaced by <to>.

  * "substitute-path remove" removes the current substitution rule
    if one was specified. No effect otherwise.

  * "substitute-path" prints the current substitution rule.

Some users argued that "substitute-path show" should also be added.
I think it's mostly aesthetic, and hence passed on this suggestion,
but I can do that as well if others think it'd be nice to have it.

At least one user suggested that we provide the possibility of applying
a list of substitution rules as opposed to one. I'm not against that
idea, but this makes the design and implementation slightly more complex
for something that I think will be little used. I suspect that most
people will use it in a very specific context where the entire source
tree has been moved - so one substitution rule should be enough.

Nonetheless, should anybody require this feature, there is an upward
compatible way of enhancing my implementation later on. The "add"
command remains the same. The "remove" command without any argument
would delete all substitution rules. And with a "from" argument, it
would remove the rule that matches "from". The "substitute-path"
command would print all substitution rules, not just the one.

Here is how I tested it:

        * In a root directory, I have some sources in src/
        * cd to src/, and compile the sources
        * cd <root>, cp -R src dup
        * cd src/, modify one line of my source file
        * gdb dup/my_program
          (gdb) substitute-path add src dup
          (gdb) list my_program.c:1

With the current debugger, GDB will list src/my_program.c. But in
fact, this is no longer the file that was used to build the program
we're actually debugging. With the patch I am suggesting, the debugger
lists dup/my_program.c.

The "substitute-path" has two uses that I can see, each of them when
the path to the source tree available to GDB is different from the path
when the program was built:

  . 1: The path to the source tree is no longer valid for whatever
       reason. In that case, the "dir" command can be used to point
       GDB to the current location. But larger programs may use a
       full tree of directories, making it painful because one has
       to use a series of "dir" commands, one per directory. This
       new command makes it easier.

  . 2: The path to the source tree is still valid. This is the case
       I explained in my message on gdb@. Please refer to it for more
       details. In this case, this new command is the only way to make
       sure GDB uses the right sources.

Question: Is a MI equivalent needed?

2006-07-05  Joel Brobecker  <brobecker@adacore.com

        * source.c (substitute_path_from): New static variable.
        (substitute_path_to): Likewise.
        (substitute_path_cmdlist): Likewise.
        (xrewrite_source_path): New function.
        (find_and_open_source): Add source path rewriting support.
        (substitute_path_command): New function.
        (xextract_path_argument): New function.
        (substitute_path_remove_command): New function.
        (substitute_path_add_command): New function.
        (_initialize_source): Add new substitute-path commands.

Tested on x86-linux, no regression. I wouldn't mind adding a testcase
for this new feature, but I'm not sure yet how to achieve this.

Documentation & NEWS update will be sent if the feature is accepted.

Thanks,
-- 
Joel

[-- Attachment #2: subst.diff --]
[-- Type: text/plain, Size: 8646 bytes --]

Index: source.c
===================================================================
RCS file: /cvs/src/src/gdb/source.c,v
retrieving revision 1.75
diff -u -p -r1.75 source.c
--- source.c	15 May 2006 15:50:13 -0000	1.75
+++ source.c	5 Jul 2006 21:46:11 -0000
@@ -73,6 +73,13 @@ static void show_directories (char *, in
 
 char *source_path;
 
+/* Support for source path substitution commands.  */
+
+static char *substitute_path_from = NULL;
+static char *substitute_path_to = NULL;
+
+static struct cmd_list_element *substitute_path_cmdlist;
+
 /* Symtab of default file for listing lines of.  */
 
 static struct symtab *current_source_symtab;
@@ -828,6 +835,47 @@ source_full_path_of (char *filename, cha
   return 1;
 }
 
+/* If the user specified a source path substitution rule, then
+   try applying it on PATH, and return the new path.  This new
+   path must be deallocated afterwards.
+   
+   Return NULL if no substitution rule was specified by the user,
+   or of this rule didn't apply to the given PATH.  */
+   
+static char *
+xrewrite_source_path (const char *path)
+{
+  char *from_start;
+  char *new_path;
+
+  /* If no path substitution rule was specified, then no rewrite
+     is actually needed.  */
+
+  if (substitute_path_from == NULL)
+    return NULL;
+
+  /* Search for the first occurence of SUBSTITUTE_PATH_FROM.
+     No substitution needed of not found.  */
+
+  from_start = strstr (path, substitute_path_from);
+
+  if (from_start == NULL)
+    return NULL;
+
+  /* Compute the rewritten path and return it.  */
+
+  new_path = (char *) malloc (strlen (path) + 1
+                              + strlen (substitute_path_to)
+                              - strlen (substitute_path_from));
+  strncpy (new_path, path, from_start - path);
+  strcpy (new_path + (from_start - path),
+          substitute_path_to);
+  strcat (new_path,
+          from_start + strlen (substitute_path_from));
+
+  return new_path;
+}
+
 /* This function is capable of finding the absolute path to a
    source file, and opening it, provided you give it an 
    OBJFILE and FILENAME. Both the DIRNAME and FULLNAME are only
@@ -844,7 +892,7 @@ source_full_path_of (char *filename, cha
      FULLNAME is set to the absolute path to the file just opened.
 
    On Failure
-     A non valid file descriptor is returned. ( the return value is negitive ) 
+     A non valid file descriptor is returned. ( the return value is negative ) 
      FULLNAME is set to NULL.  */
 int
 find_and_open_source (struct objfile *objfile,
@@ -857,8 +905,22 @@ find_and_open_source (struct objfile *ob
   int result;
 
   /* Quick way out if we already know its full name */
+
   if (*fullname)
     {
+      {
+        /* The user may have requested that source paths be rewritten
+           according to a substitution rule he provided.  Check if
+           this is the case, and do the rewrite if appropriate.  */
+        char *rewritten_fullname = xrewrite_source_path (*fullname);
+
+        if (rewritten_fullname != NULL)
+           {
+             xfree (*fullname);
+             *fullname = rewritten_fullname;
+           }
+      }
+
       result = open (*fullname, OPEN_MODE);
       if (result >= 0)
 	return result;
@@ -869,6 +931,27 @@ find_and_open_source (struct objfile *ob
 
   if (dirname != NULL)
     {
+      /* If necessary, rewrite the compilation directory name according
+         to the source path substitution rules specified by the user.
+
+         Normally, we should really try to do the rewrite on the entire
+         path as opposed to just the directory name, but that's making
+         things much more complicated since we now have to concat the
+         dirname and filename, apply the substitution rule, and then do
+         [...] ???  How do we split the path back into dirname and filename?
+         In practice, the source path substitution feature should be used
+         when the entire tree has been moved, in which case only the root
+         part of the tree path will need to be rewritten.  So this should
+         not be a problem in practice.  */
+
+      char *rewritten_dirname = xrewrite_source_path (dirname);
+
+      if (rewritten_dirname != NULL)
+        {
+          make_cleanup (xfree, rewritten_dirname);
+          dirname = rewritten_dirname;
+        }
+      
       /* Replace a path entry of  $cdir  with the compilation directory name */
 #define	cdir_len	5
       /* We cast strstr's result in case an ANSIhole has made it const,
@@ -1587,6 +1670,129 @@ reverse_search_command (char *regex, int
   fclose (stream);
   return;
 }
+
+/* Print the current source path substitution rule.  */
+
+static void
+substitute_path_command (char *args, int from_tty)
+{
+  if (substitute_path_from == NULL)
+    printf_filtered (_("No source path substitution rule specified.\n"));
+  else
+    printf_filtered (_("`%s' in source paths now substituted with `%s'.\n"),
+                     substitute_path_from, substitute_path_to);
+}
+
+/* Extract the first argument (possibly quoted) from ARGS, and return it.
+   ARGS is updated to point right after that first argument.
+   The returned value must be deallocated afterwards.
+   
+   Return NULL is an argument could not be found.  */
+
+static char *
+xextract_path_argument (char **args)
+{
+  int is_quoted;
+  char *p;
+  int arg_len;
+  char *path;
+
+  /* First, skip any leading white spaces, and check that we have
+     at least one character left after the trimming.  */
+
+  while (isspace (**args))
+    (*args)++;
+  
+  if (**args == '\0')
+    return NULL;
+
+  /* Find the first character after the first argument.  */
+
+  p = skip_quoted_chars (*args, NULL, " \t");
+  arg_len = p - *args;
+
+  /* If the path was quoted, then remove the quotes.  */
+
+  is_quoted = (strchr (get_gdb_completer_quote_characters (), **args) != NULL);
+  if (is_quoted)
+    {
+      if (strchr (get_gdb_completer_quote_characters (),
+                  (*args)[arg_len - 1]) == NULL)
+        error (_("missing closing quote in argument: %s"), *args);
+
+      arg_len -= 2;
+      (*args)++;
+    }
+
+  /* If the argument is empty, then there is no real path, and hence
+     treat this as if the argumet was missing.  */
+
+  if (arg_len < 1)
+    return NULL;
+
+  path = (char *) xmalloc ((arg_len + 1) * sizeof (char));
+  strncpy (path, *args, arg_len);
+  path[arg_len] = '\0';
+
+  *args = p;
+
+  return path;
+}
+
+/* Delete the current source path substitution rule.  */
+
+static void
+substitute_path_remove_command (char *args, int from_tty)
+{
+  if (substitute_path_from != NULL)
+    {
+      xfree (substitute_path_from);
+      substitute_path_from = NULL;
+    }
+
+  if (substitute_path_to != NULL)
+    {
+      xfree (substitute_path_to);
+      substitute_path_to = NULL;
+    }
+}
+
+/* Add a new source path substitution rule.  */
+
+static void
+substitute_path_add_command (char *args, int from_tty)
+{
+  char *from_path, *to_path;
+
+  /* Extract the arguments from the command line.  */
+
+  if (args == NULL)
+    error (_("Argument missing in command"));
+
+  from_path = xextract_path_argument (&args);
+  if (from_path == NULL)
+    error (_("Argument missing in command"));
+
+  to_path = xextract_path_argument (&args);
+  if (to_path == NULL)
+    {
+      xfree (from_path);
+      error (_("Argument missing in command"));
+    }
+
+  /* Remove any previous substitution rule.  */
+
+  substitute_path_remove_command (NULL, from_tty);
+
+  /* Insert the new substitution rule, and print a confirmation message
+     to the user.  */
+
+  substitute_path_from = from_path;
+  substitute_path_to = to_path;
+
+  substitute_path_command (NULL, from_tty);
+}
+
 \f
 void
 _initialize_source (void)
@@ -1666,4 +1872,22 @@ Show number of source lines gdb will lis
 			    NULL,
 			    show_lines_to_list,
 			    &setlist, &showlist);
+
+  add_prefix_cmd ("substitute-path", class_files, substitute_path_command,
+                  _("Show the current source path substitution rule."),
+                  &substitute_path_cmdlist, "substitute-path ",
+                  0 /* allow-unknown */, &cmdlist);
+
+  add_cmd ("add", class_files, substitute_path_add_command,
+           _("\
+Add a source path substitution rule. If a substitution rule was previously\n\
+set, it is overridden."),
+           &substitute_path_cmdlist);
+
+  add_cmd ("remove", class_files, substitute_path_remove_command,
+           _("\
+Remove the current source path substitution rule.  Has no effect\n\
+if no path substitution rule was previously specified."),
+           &substitute_path_cmdlist);
+
 }

Re: [RFA] New substitute-path commands

[Andreas Schwab]

Joel Brobecker <brobecker@adacore.com> writes:

> Some users argued that "substitute-path show" should also be added.

Actually it should be "show substitute-path", cf. "show directories".

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
PGP key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: [RFA] New substitute-path commands

[Daniel Jacobowitz]

On Wed, Jul 05, 2006 at 02:56:06PM -0700, Joel Brobecker wrote:
>         (gdb) substitute-path add <from> <to>
>         (gdb) substitute-path remove
>         (gdb) substitute-path
> 
>   * "substitute-path add" adds a substitution rule, where the first
>     instance of <from> is replaced by <to>.
> 
>   * "substitute-path remove" removes the current substitution rule
>     if one was specified. No effect otherwise.
> 
>   * "substitute-path" prints the current substitution rule.

Given your later explanation that you only support one entry, I find
"substitute-path add" a bit confusing.  Shall we take a moment to think
about a general interface for lists?

If we had one, we could use it for other variables, and we could access
this using something like -gdb-set.

-- 
Daniel Jacobowitz
CodeSourcery

Re: [RFA] New substitute-path commands

[Eli Zaretskii]

> Date: Wed, 5 Jul 2006 14:56:06 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> 
> +  new_path = (char *) malloc (strlen (path) + 1
> +                              + strlen (substitute_path_to)
> +                              - strlen (substitute_path_from));
> +  strncpy (new_path, path, from_start - path);

Why did you use malloc instead of xmalloc here?

Re: [RFA] New substitute-path commands

[Joel Brobecker]

> > +  new_path = (char *) malloc (strlen (path) + 1
> > +                              + strlen (substitute_path_to)
> > +                              - strlen (substitute_path_from));
> > +  strncpy (new_path, path, from_start - path);
> 
> Why did you use malloc instead of xmalloc here?

Because I didn't pay attention ? That was an oversight on my part.
Good catch, thanks.

-- 
Joel

Re: [RFA] New substitute-path commands

[Joel Brobecker]

> Given your later explanation that you only support one entry, I find
> "substitute-path add" a bit confusing.  Shall we take a moment to think
> about a general interface for lists?
> 
> If we had one, we could use it for other variables, and we could access
> this using something like -gdb-set.

Would you mind making a design proposal? I'm not sure to understand
what you exactly you are thinking about. I think I understand the fact
that you would like to have more than one rule because "add" doesn't
suggest "replace", but I am not sure I get the rest :-/.

Thanks,
-- 
Joel

Re: [RFA] New substitute-path commands

[Andrew STUBBS]

Joel Brobecker wrote:
> At least one user suggested that we provide the possibility of applying
> a list of substitution rules as opposed to one. I'm not against that
> idea, but this makes the design and implementation slightly more complex
> for something that I think will be little used. I suspect that most
> people will use it in a very specific context where the entire source
> tree has been moved - so one substitution rule should be enough.

Another use case would be where one is trying to identify a problem in a 
library. There may be many of these and each could be in its own source 
tree.

We, here at ST, include a number of libraries (Newlib, our OS, posix 
etc.) with our toolsets, all with debug information built in. We make 
the sources available to our customers, either as part of the 
installation or a separate package, but we have no knowledge of where 
they will install them in their own systems and there is no reason why 
the various parts have to be installed in the same place.

It would be very useful if the ability to add multiple substitutions 
were there from the start.

Additionally, it would be nice if there were a command line option for 
this, similar to --directory, although --eval-command will do the job.

> +/* Extract the first argument (possibly quoted) from ARGS, and return it.
> +   ARGS is updated to point right after that first argument.
> +   The returned value must be deallocated afterwards.
> +   
> +   Return NULL is an argument could not be found.  */

What's wrong with buildargv() in libiberty?

Andrew Stubbs

Re: [RFA] New substitute-path commands

[PAUL GILLIAM]

On Wed, 2006-07-05 at 21:47 -0700, Joel Brobecker wrote:
> > Given your later explanation that you only support one entry, I find
> > "substitute-path add" a bit confusing.  Shall we take a moment to think
> > about a general interface for lists?
> > 
> > If we had one, we could use it for other variables, and we could access
> > this using something like -gdb-set.
> 
> Would you mind making a design proposal? I'm not sure to understand
> what you exactly you are thinking about. I think I understand the fact
> that you would like to have more than one rule because "add" doesn't
> suggest "replace", but I am not sure I get the rest :-/.
> 
> Thanks,

How about something like this:

	set substitute-path [<path>]
		If this variable is set, <path> is a colon-separated
		list of <from>,<to> pairs.  When a full path that
		has been encoded in the debug information is processed,
		each <from>,<to> pair is applied by searching the full
		path for the <from> string and replacing it by the <to>
		string.  If <path> is not used, then the substitute-path
		variable is un-set.

	show substitute-path
		Display the current list of <from>,<to> pairs.

Re: [RFA] New substitute-path commands

[Daniel Jacobowitz]

On Thu, Jul 06, 2006 at 08:03:19AM -0700, PAUL GILLIAM wrote:
> > Would you mind making a design proposal? I'm not sure to understand
> > what you exactly you are thinking about. I think I understand the fact
> > that you would like to have more than one rule because "add" doesn't
> > suggest "replace", but I am not sure I get the rest :-/.

Right.

> How about something like this:
> 
> 	set substitute-path [<path>]
> 		If this variable is set, <path> is a colon-separated
> 		list of <from>,<to> pairs.  When a full path that
> 		has been encoded in the debug information is processed,
> 		each <from>,<to> pair is applied by searching the full
> 		path for the <from> string and replacing it by the <to>
> 		string.  If <path> is not used, then the substitute-path
> 		variable is un-set.
> 
> 	show substitute-path
> 		Display the current list of <from>,<to> pairs.

Well, I was thinking like this:

(gdb) help set env
Set environment variable value to give the program.
Arguments are VAR VALUE where VAR is variable name and VALUE is value.
VALUES of environment variables are uninterpreted strings.
This does not affect the program until the next "run" command.
(gdb) help unset env
Cancel environment variable VAR for the program.
This does not affect the program until the next "run" command.
(gdb) help show env
The environment to give the program, or one variable's value.
With an argument VAR, prints the value of environment variable VAR to
give the program being debugged.  With no arguments, prints the entire
environment to be given to the program.

This isn't a list; it's more like a dictionary or hash table.  But that
ought to work too, right?  I don't think we need to support ordered
substitutions, like "map /foo/bar to /one but all other /foo to /two". 
If we need that, we should hook up a scripting language and say "pass
all source paths to this python function and use the result".  Which is
actually a kind of nice idea, but overkill for the moment.

There's already a "-gdb-show env", although its output is not very
useful to a frontend.  We could change that for MI3 if anyone cares.
I don't think there's a -gdb-unset, but the parallel is fairly obvious,
so we could add one readily.

That gives us:

set substitute-path FROM TO

  [We can make it use buildargv for uniform quoting of TO and FROM. 
  I'd recommend that.]

unset substitute-path FROM

show substitute-path

-- 
Daniel Jacobowitz
CodeSourcery

Re: [RFA] New substitute-path commands

[Jason Molenda]

On Jul 5, 2006, at 2:56 PM, Joel Brobecker wrote:

> The new commands are:
>
>         (gdb) substitute-path add <from> <to>
>         (gdb) substitute-path remove
>         (gdb) substitute-path

For what it's worth we added a similar facility to Apple gdb.  Our  
command isn't very fancy:

(gdb) apropos pathname-sub
set pathname-substitutions -- Set string substitutions to be used when  
searching for source files
show pathname-substitutions -- Show string substitutions to be used  
when searching for source files

It takes a series of directory pairs, e.g.

(gdb) set pathname-substitutions /old1 /new1 /old2 /new2

etc.  It uses buildargv to parse the arguments so they can be quoted.   
Making it a standard set/show command gets us MI support for free.

J

Re: [RFA] New substitute-path commands

[Joel Brobecker]

> set substitute-path FROM TO
> 
>   [We can make it use buildargv for uniform quoting of TO and FROM. 
>   I'd recommend that.]
> 
> unset substitute-path FROM
> 
> show substitute-path

Okidoki - This sounds very nice to me. Will try implementing this
shortly. Thanks to everyone for the nice feedback - including the
suggestion to use build_argv from libiberty. I was looking for that!

-- 
Joel

Re: [RFA] New substitute-path commands

[Joel Brobecker]

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

Hello,

Here is a second take at this new functionality, updated as suggested:

> set substitute-path FROM TO
> 
>   [We can make it use buildargv for uniform quoting of TO and FROM. 
>   I'd recommend that.]
> 
> unset substitute-path FROM
> 
> show substitute-path

Added bonus, I included a documentation patch for review.

2006-07-06  Joel Brobecker  <brobecker@adacore.com

        * source.c (substitute_path_from): New static variable.
        (substitute_path_to): Likewise.
        (xrewrite_source_path): New function.
        (find_and_open_source): Add source path rewriting support.
        (show_substitute_path_command): New function.
        (unset_substitute_path_command): New function.
        (set_substitute_path_command): New function.
        (_initialize_source): Add new substitute-path commands.

Documentation ChangeLog entry:

        * gdb.texinfo (Source Path): Add documentation for new
        substitute-path commands.

Tested on x86-linux, no regression.

Thanks,
-- 
Joel

[-- Attachment #2: subst.diff --]
[-- Type: text/plain, Size: 6910 bytes --]

Index: source.c
===================================================================
RCS file: /cvs/src/src/gdb/source.c,v
retrieving revision 1.75
diff -u -p -r1.75 source.c
--- source.c	15 May 2006 15:50:13 -0000	1.75
+++ source.c	7 Jul 2006 04:50:31 -0000
@@ -73,6 +73,11 @@ static void show_directories (char *, in
 
 char *source_path;
 
+/* Support for source path substitution commands.  */
+
+static char *substitute_path_from = NULL;
+static char *substitute_path_to = NULL;
+
 /* Symtab of default file for listing lines of.  */
 
 static struct symtab *current_source_symtab;
@@ -828,6 +833,47 @@ source_full_path_of (char *filename, cha
   return 1;
 }
 
+/* If the user specified a source path substitution rule, then
+   try applying it on PATH, and return the new path.  This new
+   path must be deallocated afterwards.
+   
+   Return NULL if no substitution rule was specified by the user,
+   or of this rule didn't apply to the given PATH.  */
+   
+static char *
+xrewrite_source_path (const char *path)
+{
+  char *from_start;
+  char *new_path;
+
+  /* If no path substitution rule was specified, then no rewrite
+     is actually needed.  */
+
+  if (substitute_path_from == NULL)
+    return NULL;
+
+  /* Search for the first occurence of SUBSTITUTE_PATH_FROM.
+     No substitution needed of not found.  */
+
+  from_start = strstr (path, substitute_path_from);
+
+  if (from_start == NULL)
+    return NULL;
+
+  /* Compute the rewritten path and return it.  */
+
+  new_path = (char *) xmalloc (strlen (path) + 1
+                               + strlen (substitute_path_to)
+                               - strlen (substitute_path_from));
+  strncpy (new_path, path, from_start - path);
+  strcpy (new_path + (from_start - path),
+          substitute_path_to);
+  strcat (new_path,
+          from_start + strlen (substitute_path_from));
+
+  return new_path;
+}
+
 /* This function is capable of finding the absolute path to a
    source file, and opening it, provided you give it an 
    OBJFILE and FILENAME. Both the DIRNAME and FULLNAME are only
@@ -844,7 +890,7 @@ source_full_path_of (char *filename, cha
      FULLNAME is set to the absolute path to the file just opened.
 
    On Failure
-     A non valid file descriptor is returned. ( the return value is negitive ) 
+     A non valid file descriptor is returned. ( the return value is negative ) 
      FULLNAME is set to NULL.  */
 int
 find_and_open_source (struct objfile *objfile,
@@ -857,8 +903,22 @@ find_and_open_source (struct objfile *ob
   int result;
 
   /* Quick way out if we already know its full name */
+
   if (*fullname)
     {
+      {
+        /* The user may have requested that source paths be rewritten
+           according to a substitution rule he provided.  Check if
+           this is the case, and do the rewrite if appropriate.  */
+        char *rewritten_fullname = xrewrite_source_path (*fullname);
+
+        if (rewritten_fullname != NULL)
+           {
+             xfree (*fullname);
+             *fullname = rewritten_fullname;
+           }
+      }
+
       result = open (*fullname, OPEN_MODE);
       if (result >= 0)
 	return result;
@@ -869,6 +929,27 @@ find_and_open_source (struct objfile *ob
 
   if (dirname != NULL)
     {
+      /* If necessary, rewrite the compilation directory name according
+         to the source path substitution rules specified by the user.
+
+         Normally, we should really try to do the rewrite on the entire
+         path as opposed to just the directory name, but that's making
+         things much more complicated since we now have to concat the
+         dirname and filename, apply the substitution rule, and then do
+         [...] ???  How do we split the path back into dirname and filename?
+         In practice, the source path substitution feature should be used
+         when the entire tree has been moved, in which case only the root
+         part of the tree path will need to be rewritten.  So this should
+         not be a problem in practice.  */
+
+      char *rewritten_dirname = xrewrite_source_path (dirname);
+
+      if (rewritten_dirname != NULL)
+        {
+          make_cleanup (xfree, rewritten_dirname);
+          dirname = rewritten_dirname;
+        }
+      
       /* Replace a path entry of  $cdir  with the compilation directory name */
 #define	cdir_len	5
       /* We cast strstr's result in case an ANSIhole has made it const,
@@ -1587,6 +1668,65 @@ reverse_search_command (char *regex, int
   fclose (stream);
   return;
 }
+
+/* Print the current source path substitution rule.  */
+
+static void
+show_substitute_path_command (char *args, int from_tty)
+{
+  if (substitute_path_from == NULL)
+    printf_filtered (_("No source path substitution rule specified.\n"));
+  else
+    printf_filtered (_("`%s' in source paths now substituted with `%s'.\n"),
+                     substitute_path_from, substitute_path_to);
+}
+
+/* Delete the current source path substitution rule.  */
+
+static void
+unset_substitute_path_command (char *args, int from_tty)
+{
+  if (substitute_path_from != NULL)
+    {
+      xfree (substitute_path_from);
+      substitute_path_from = NULL;
+    }
+
+  if (substitute_path_to != NULL)
+    {
+      xfree (substitute_path_to);
+      substitute_path_to = NULL;
+    }
+}
+
+/* Add a new source path substitution rule.  */
+
+static void
+set_substitute_path_command (char *args, int from_tty)
+{
+  char *from_path, *to_path;
+  char **argv = buildargv (args);
+
+  if (argv == NULL || argv[0] == NULL || argv [1] == NULL)
+    error (_("Incorrect usage, too few arguments in command"));
+
+  if (argv[2] != NULL)
+    error (_("Incorrect usage, too many arguments in command"));
+
+  /* Remove any previous substitution rule.  */
+
+  unset_substitute_path_command (NULL, from_tty);
+
+  /* Insert the new substitution rule, and print a confirmation message
+     to the user.  */
+
+  substitute_path_from = xstrdup (argv[0]);
+  substitute_path_to = xstrdup (argv[1]);
+  freeargv (argv);
+
+  show_substitute_path_command (NULL, from_tty);
+}
+
 \f
 void
 _initialize_source (void)
@@ -1666,4 +1806,19 @@ Show number of source lines gdb will lis
 			    NULL,
 			    show_lines_to_list,
 			    &setlist, &showlist);
+
+  add_cmd ("substitute-path", class_files, set_substitute_path_command,
+           _("\
+Add a source path substitution rule. If a substitution rule was previously\n\
+set, it is overridden."), &setlist);
+
+  add_cmd ("substitute-path", class_files, unset_substitute_path_command,
+           _("\
+Remove the current source path substitution rule.  Has no effect\n\
+if no path substitution rule was previously specified."),
+           &unsetlist);
+
+  add_cmd ("substitute-path", class_files, show_substitute_path_command,
+           _("Show the current source path substitution rule."),
+           &showlist);
 }

[-- Attachment #3: subst-doc.diff --]
[-- Type: text/plain, Size: 2302 bytes --]

Index: doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.340
diff -u -p -r1.340 gdb.texinfo
--- doc/gdb.texinfo	21 Jun 2006 13:57:21 -0000	1.340
+++ doc/gdb.texinfo	7 Jul 2006 04:51:00 -0000
@@ -5033,6 +5033,23 @@ To add other directories, use the @code{
 The search path is used to find both program source files and @value{GDBN}
 script files (read using the @samp{-command} option and @samp{source} command).
 
+In addition to the source path, @value{GDBN} provides a set of commands
+that manage a source path substitution rule.  Instead of attempting to
+locate the source file using the original source path as described above,
+it will first apply the substitution rule to that source path, and use
+the resulting path instead.  By default, there is no substitution rule
+defined, but this can be very useful in the case when your source tree
+has been moved to a different location from the one where the sources
+were compiled. To define a source path substitution rule, use the
+@code{set substitute-path} command.
+
+Using the previous example, suppose the @file{foo-1.0} tree has been
+moved from @file{/usr/src} to @file{/mnt/cross}, then you can tell
+GDB to replace @file{/usr/src} in all source path names with
+@file{/mnt/cross}.  The first lookup will then be
+@file{/mnt/cross/foo-1.0/lib/foo.c} in place of the original location
+of @file{/usr/src/foo-1.0/lib/foo.c}.
+
 @table @code
 @item directory @var{dirname} @dots{}
 @item dir @var{dirname} @dots{}
@@ -5068,6 +5085,21 @@ Reset the source path to its default val
 @item show directories
 @kindex show directories
 Print the source path: show which directories it contains.
+
+@item set substitute-path @var{FROM} @var{TO}
+@kindex set substitute-path
+Define a source path substitution rule.  The new substitution rule
+replaces any rule previously defined.
+
+@item unset substitute-path
+@kindex unset substitute-path
+If a source path substitution rule is active, then cancel it.
+This command has no effect otherwise.
+
+@item show substitute-path
+@kindex show substitute-path
+Print the source path substitution rule if defined.
+
 @end table
 
 If your source path is cluttered with directories that are no longer of

Re: [RFA] New substitute-path commands

[Eli Zaretskii]

> Date: Thu, 6 Jul 2006 22:22:19 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> 
> Added bonus, I included a documentation patch for review.

Thanks.  My comments are below.

> -     A non valid file descriptor is returned. ( the return value is negitive ) 
> +     A non valid file descriptor is returned. ( the return value is negative ) 

"non valid"?  Is that correct English?  I think "invalid" is better.

> +Add a source path substitution rule. If a substitution rule was previously\n\
                                      ^^^
Two spaces here, please.

> +Remove the current source path substitution rule.  Has no effect\n\
> +if no path substitution rule was previously specified."),

"This has no effect" is better, I think.

> +In addition to the source path, @value{GDBN} provides a set of commands
> +that manage a source path substitution rule.

The term "substitution rule" should be explained somewhere.  I think
the best place to do so is where the command "set substitute-path" is
described (see below), in which case you should add here a
cross-reference to that description.

>                                                  Instead of attempting to
> +locate the source file using the original source path as described above,
> +it will first apply the substitution rule to that source path, and use
> +the resulting path instead.

If this was meant to explain what is a substitution rule, then it
doesn't explain enough.

> +were compiled. To define a source path substitution rule, use the
> +@code{set substitute-path} command.

A cross-reference here would be a good idea.

> +Using the previous example, suppose the @file{foo-1.0} tree has been
> +moved from @file{/usr/src} to @file{/mnt/cross}, then you can tell
> +GDB to replace @file{/usr/src} in all source path names with
> +@file{/mnt/cross}.  The first lookup will then be
> +@file{/mnt/cross/foo-1.0/lib/foo.c} in place of the original location
> +of @file{/usr/src/foo-1.0/lib/foo.c}.

This is a start, but it lacks the "set substitute-path" command to go
with the example.

> +@item set substitute-path @var{FROM} @var{TO}

The arguments of @var{} should not be in UPPER case.  They are
automatically upcased by makeinfo when it produces the Info manual,
but in other formats they come out in italics, so having them in upper
case in the source will produce less optimal results.

> +@kindex set substitute-path
> +Define a source path substitution rule.  The new substitution rule
> +replaces any rule previously defined.

As I said above, an explanation of what is a substitution rule is in
order here.  Something like this:

  A @dfn{substitution rule} specifies how to rewrite source
  directories stored in the program's debug information in case the
  sources were moved to a different directory between compilation and
  debugging.  @value{GDBN} does a simple string replacement of each
  occurrence of @var{from} with @var{to} in the directory part of the
  source file name, and uses the result instead of the original file
  name to look up the sources.

  For example, if the file @file{/foo/bar/baz.c} was moved to
  @file{mnt/cross/baz.c}, then the command

  @smallexample
  (@value{GDBP}) set substitute-path /usr/src /mnt/cross
  @end smallexample

  @noindent
  will tell @value{GDBN} to replace @samp{/usr/src} with
  @samp{/mnt/cross}, which will allow @value{GDBN} to find the file
  @file{baz.c} even though it was moved.

Re: [RFA] New substitute-path commands

[Andrew STUBBS]

Joel Brobecker wrote:
> +@item unset substitute-path
> +@kindex unset substitute-path
> +If a source path substitution rule is active, then cancel it.
> +This command has no effect otherwise.

I think the suggested interface allowed a FROM argument for removing 
that substitution alone. I still think this feature would be nice to have.

Andrew

Re: [RFA] New substitute-path commands

[Joel Brobecker]

> I think the suggested interface allowed a FROM argument for removing 
> that substitution alone. I still think this feature would be nice to have.

Currently, we only provide one substitution rule, so the extra argument
at this moment is not needed. My understanding is that, should more than
one rule be needed, the plan is to provide this through a different type
of interface - See Daniel's message.

-- 
Joel

Re: [RFA] New substitute-path commands

[Andrew STUBBS]

Joel Brobecker wrote:
>> I think the suggested interface allowed a FROM argument for removing 
>> that substitution alone. I still think this feature would be nice to have.
> 
> Currently, we only provide one substitution rule, so the extra argument
> at this moment is not needed. My understanding is that, should more than
> one rule be needed, the plan is to provide this through a different type
> of interface - See Daniel's message.

Unless I misread Daniel's message, he was referring to an interface in 
which pairs of FROM/TO paths are added, one at a time, to an unordered list.

Anyway, if your implementation only allows one (I didn't read it that 
closely), then the extra argument clearly isn't necessary.

I would still like to see a solution where more than one mapping was 
allowed, one for each of our various libraries, not to mention the 
header files. I want to be able to ship our toolset to customers with a 
number of 'preset' mappings, computed from the install location, and 
still allow them to use the feature for their own sources.

Andrew

Re: [RFA] New substitute-path commands

[Joel Brobecker]

> I would still like to see a solution where more than one mapping was 
> allowed, one for each of our various libraries, not to mention the 
> header files. I want to be able to ship our toolset to customers with a 
> number of 'preset' mappings, computed from the install location, and 
> still allow them to use the feature for their own sources.

I guess the implementation would be easy to extend without changing
the user interface (or rather extending the user interface). It just
a bit of time, and I would prefer to keep that for another update of
this patch. In the meantime, your users can still use the "dir" command
to achieve what they need, right?

-- 
Joel

Re: [RFA] New substitute-path commands

[Joel Brobecker]

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

Hi Eli,

> Thanks.  My comments are below.

Thanks for your review (and also the effort you made in providing a
description of what a substitution rule is, much appreciated). I have
updated the source as per your comments, as well as reworked the
documentation to include your ideas. I also took the time to include a
small explaination of how this new functionality differs slightly from
the "dir" command. It's not necessary since the explaination can be
deduced from the rest of the documentation, but might make it easier to
figure this out.

2006-07-07  Joel Brobecker  <brobecker@adacore.com

        * source.c (substitute_path_from): New static variable.
        (substitute_path_to): Likewise.
        (xrewrite_source_path): New function.
        (find_and_open_source): Add source path rewriting support.
        (show_substitute_path_command): New function.
        (unset_substitute_path_command): New function.
        (set_substitute_path_command): New function.
        (_initialize_source): Add new substitute-path commands.

Documentation ChangeLog entry:

2006-07-07  Joel Brobecker  <brobecker@adacore.com

        * gdb.texinfo (Source Path): Add documentation for new
        substitute-path commands.

Tested on x86-linux. I forgot to mention that this patch will
also require a small adjustment in the "help unset" test of help.exp.
Will do so immediately.

-- 
Joel

[-- Attachment #2: subst.diff --]
[-- Type: text/plain, Size: 6915 bytes --]

Index: source.c
===================================================================
RCS file: /cvs/src/src/gdb/source.c,v
retrieving revision 1.75
diff -u -p -r1.75 source.c
--- source.c	15 May 2006 15:50:13 -0000	1.75
+++ source.c	7 Jul 2006 19:02:04 -0000
@@ -73,6 +73,11 @@ static void show_directories (char *, in
 
 char *source_path;
 
+/* Support for source path substitution commands.  */
+
+static char *substitute_path_from = NULL;
+static char *substitute_path_to = NULL;
+
 /* Symtab of default file for listing lines of.  */
 
 static struct symtab *current_source_symtab;
@@ -828,6 +833,47 @@ source_full_path_of (char *filename, cha
   return 1;
 }
 
+/* If the user specified a source path substitution rule, then
+   try applying it on PATH, and return the new path.  This new
+   path must be deallocated afterwards.
+   
+   Return NULL if no substitution rule was specified by the user,
+   or of this rule didn't apply to the given PATH.  */
+   
+static char *
+xrewrite_source_path (const char *path)
+{
+  char *from_start;
+  char *new_path;
+
+  /* If no path substitution rule was specified, then no rewrite
+     is actually needed.  */
+
+  if (substitute_path_from == NULL)
+    return NULL;
+
+  /* Search for the first occurence of SUBSTITUTE_PATH_FROM.
+     No substitution needed of not found.  */
+
+  from_start = strstr (path, substitute_path_from);
+
+  if (from_start == NULL)
+    return NULL;
+
+  /* Compute the rewritten path and return it.  */
+
+  new_path = (char *) xmalloc (strlen (path) + 1
+                               + strlen (substitute_path_to)
+                               - strlen (substitute_path_from));
+  strncpy (new_path, path, from_start - path);
+  strcpy (new_path + (from_start - path),
+          substitute_path_to);
+  strcat (new_path,
+          from_start + strlen (substitute_path_from));
+
+  return new_path;
+}
+
 /* This function is capable of finding the absolute path to a
    source file, and opening it, provided you give it an 
    OBJFILE and FILENAME. Both the DIRNAME and FULLNAME are only
@@ -844,7 +890,7 @@ source_full_path_of (char *filename, cha
      FULLNAME is set to the absolute path to the file just opened.
 
    On Failure
-     A non valid file descriptor is returned. ( the return value is negitive ) 
+     An invalid file descriptor is returned. ( the return value is negative ) 
      FULLNAME is set to NULL.  */
 int
 find_and_open_source (struct objfile *objfile,
@@ -857,8 +903,22 @@ find_and_open_source (struct objfile *ob
   int result;
 
   /* Quick way out if we already know its full name */
+
   if (*fullname)
     {
+      {
+        /* The user may have requested that source paths be rewritten
+           according to a substitution rule he provided.  Check if
+           this is the case, and do the rewrite if appropriate.  */
+        char *rewritten_fullname = xrewrite_source_path (*fullname);
+
+        if (rewritten_fullname != NULL)
+           {
+             xfree (*fullname);
+             *fullname = rewritten_fullname;
+           }
+      }
+
       result = open (*fullname, OPEN_MODE);
       if (result >= 0)
 	return result;
@@ -869,6 +929,27 @@ find_and_open_source (struct objfile *ob
 
   if (dirname != NULL)
     {
+      /* If necessary, rewrite the compilation directory name according
+         to the source path substitution rules specified by the user.
+
+         Normally, we should really try to do the rewrite on the entire
+         path as opposed to just the directory name, but that's making
+         things much more complicated since we now have to concat the
+         dirname and filename, apply the substitution rule, and then do
+         [...] ???  How do we split the path back into dirname and filename?
+         In practice, the source path substitution feature should be used
+         when the entire tree has been moved, in which case only the root
+         part of the tree path will need to be rewritten.  So this should
+         not be a problem in practice.  */
+
+      char *rewritten_dirname = xrewrite_source_path (dirname);
+
+      if (rewritten_dirname != NULL)
+        {
+          make_cleanup (xfree, rewritten_dirname);
+          dirname = rewritten_dirname;
+        }
+      
       /* Replace a path entry of  $cdir  with the compilation directory name */
 #define	cdir_len	5
       /* We cast strstr's result in case an ANSIhole has made it const,
@@ -1587,6 +1668,65 @@ reverse_search_command (char *regex, int
   fclose (stream);
   return;
 }
+
+/* Print the current source path substitution rule.  */
+
+static void
+show_substitute_path_command (char *args, int from_tty)
+{
+  if (substitute_path_from == NULL)
+    printf_filtered (_("No source path substitution rule specified.\n"));
+  else
+    printf_filtered (_("`%s' in source paths now substituted with `%s'.\n"),
+                     substitute_path_from, substitute_path_to);
+}
+
+/* Delete the current source path substitution rule.  */
+
+static void
+unset_substitute_path_command (char *args, int from_tty)
+{
+  if (substitute_path_from != NULL)
+    {
+      xfree (substitute_path_from);
+      substitute_path_from = NULL;
+    }
+
+  if (substitute_path_to != NULL)
+    {
+      xfree (substitute_path_to);
+      substitute_path_to = NULL;
+    }
+}
+
+/* Add a new source path substitution rule.  */
+
+static void
+set_substitute_path_command (char *args, int from_tty)
+{
+  char *from_path, *to_path;
+  char **argv = buildargv (args);
+
+  if (argv == NULL || argv[0] == NULL || argv [1] == NULL)
+    error (_("Incorrect usage, too few arguments in command"));
+
+  if (argv[2] != NULL)
+    error (_("Incorrect usage, too many arguments in command"));
+
+  /* Remove any previous substitution rule.  */
+
+  unset_substitute_path_command (NULL, from_tty);
+
+  /* Insert the new substitution rule, and print a confirmation message
+     to the user.  */
+
+  substitute_path_from = xstrdup (argv[0]);
+  substitute_path_to = xstrdup (argv[1]);
+  freeargv (argv);
+
+  show_substitute_path_command (NULL, from_tty);
+}
+
 \f
 void
 _initialize_source (void)
@@ -1666,4 +1806,19 @@ Show number of source lines gdb will lis
 			    NULL,
 			    show_lines_to_list,
 			    &setlist, &showlist);
+
+  add_cmd ("substitute-path", class_files, set_substitute_path_command,
+           _("\
+Add a source path substitution rule.  If a substitution rule was previously\n\
+set, it is overridden."), &setlist);
+
+  add_cmd ("substitute-path", class_files, unset_substitute_path_command,
+           _("\
+Remove the current source path substitution rule.  This has no effect\n\
+if no path substitution rule was previously specified."),
+           &unsetlist);
+
+  add_cmd ("substitute-path", class_files, show_substitute_path_command,
+           _("Show the current source path substitution rule."),
+           &showlist);
 }

[-- Attachment #3: subst-doc.diff --]
[-- Type: text/plain, Size: 3744 bytes --]

Index: doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.340
diff -u -p -r1.340 gdb.texinfo
--- doc/gdb.texinfo	21 Jun 2006 13:57:21 -0000	1.340
+++ doc/gdb.texinfo	7 Jul 2006 19:02:26 -0000
@@ -5033,6 +5033,40 @@ To add other directories, use the @code{
 The search path is used to find both program source files and @value{GDBN}
 script files (read using the @samp{-command} option and @samp{source} command).
 
+In addition to the source path, @value{GDBN} provides a set of commands
+that manage a source path substitution rule.  A @dfn{substitution rule}
+specifies how to rewrite source directories stored in the program's
+debug information in case the sources were moved to a different
+directory between compilation and debugging.  @value{GDBN} does a simple
+string replacement of the first occurrence of @var{from} with @var{to}
+in the directory part of the source file name, and uses the result
+instead of the original file name to look up the sources.
+
+Using the previous example, suppose the @file{foo-1.0} tree has been
+moved from @file{/usr/src} to @file{/mnt/cross}, then you can tell
+GDB to replace @file{/usr/src} in all source path names with
+@file{/mnt/cross}.  The first lookup will then be
+@file{/mnt/cross/foo-1.0/lib/foo.c} in place of the original location
+of @file{/usr/src/foo-1.0/lib/foo.c}.  To define a source path
+substitution rule, use the @ref{set substitute-path} command.
+
+In many cases, you can achieve the same result using the @code{directory}
+command.  However, @code{set substitute-path} can be more efficient in
+the case where the sources are organized in a complex tree with multiple
+subdirectories.  With the @code{directory} command, you need to add each
+subdirectory of your project.  If you moved the entire tree while
+preserving its internal organization, then @code{set substitute-path}
+allows you to direct the debugger to all the sources with one single
+command.
+
+However, @code{set substitute-path} is also more than just a shortcut
+command.  The source path is only used if the file at the original
+location no longer exists.  On the other hand, @code{set substitute-path}
+modifies the debugger behavior to look at the rewritten location
+instead.  So, if for any reason a source file that is not relevant to
+your executable is located at the original location, the substitution
+rule is the only method available to point GDB at the new location.
+
 @table @code
 @item directory @var{dirname} @dots{}
 @item dir @var{dirname} @dots{}
@@ -5068,6 +5102,34 @@ Reset the source path to its default val
 @item show directories
 @kindex show directories
 Print the source path: show which directories it contains.
+
+@anchor{set substitute-path}
+@item set substitute-path @var{FROM} @var{TO}
+@kindex set substitute-path
+Define a source path substitution rule.  The new substitution rule
+replaces any rule previously defined.
+
+For example, if the file @file{/foo/bar/baz.c} was moved to
+@file{/mnt/cross/baz.c}, then the command
+
+@smallexample
+(@value{GDBP}) set substitute-path /usr/src /mnt/cross
+@end smallexample
+
+@noindent
+will tell @value{GDBN} to replace @samp{/usr/src} with
+@samp{/mnt/cross}, which will allow @value{GDBN} to find the file
+@file{baz.c} even though it was moved.
+
+@item unset substitute-path
+@kindex unset substitute-path
+If a source path substitution rule is active, then cancel it.
+This command has no effect otherwise.
+
+@item show substitute-path
+@kindex show substitute-path
+Print the source path substitution rule if defined.
+
 @end table
 
 If your source path is cluttered with directories that are no longer of

Re: [RFA] New substitute-path commands

[Eli Zaretskii]

> Date: Fri, 7 Jul 2006 12:12:03 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: gdb-patches@sources.redhat.com
> 
> Thanks for your review (and also the effort you made in providing a
> description of what a substitution rule is, much appreciated). I have
> updated the source as per your comments, as well as reworked the
> documentation to include your ideas.

Thanks, I'm almost happy now.

> I also took the time to include a
> small explaination of how this new functionality differs slightly from
> the "dir" command. It's not necessary since the explaination can be
> deduced from the rest of the documentation, but might make it easier to
> figure this out.

I think it's a good addition, thanks.

> +directory between compilation and debugging.  @value{GDBN} does a simple
> +string replacement of the first occurrence of @var{from} with @var{to}
> +in the directory part of the source file name, and uses the result
> +instead of the original file name to look up the sources.

I suggested to have this text after the command description.  In that
context, @var{from} and @var{to} refer to the command's arguments.
But you moved the description higher in the text, which made those
reference dangling.  So this needs to be reworded in some way.

> +However, @code{set substitute-path} is also more than just a shortcut

This However is redundant here, I think.

Re: [RFA] New substitute-path commands

[Joel Brobecker]

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

Hi Eli,

I incorporated all your comments in the this new version.

> > +directory between compilation and debugging.  @value{GDBN} does a simple
> > +string replacement of the first occurrence of @var{from} with @var{to}
> > +in the directory part of the source file name, and uses the result
> > +instead of the original file name to look up the sources.
> 
> I suggested to have this text after the command description.  In that
> context, @var{from} and @var{to} refer to the command's arguments.
> But you moved the description higher in the text, which made those
> reference dangling.  So this needs to be reworded in some way.

You're right. It didn't work that way at all. You'll see my attempt
at fixing it in this version of the patch.

2006-07-07  Joel Brobecker  <brobecker@adacore.com

        * source.c (substitute_path_from): New static variable.
        (substitute_path_to): Likewise.
        (xrewrite_source_path): New function.
        (find_and_open_source): Add source path rewriting support.
        (show_substitute_path_command): New function.
        (unset_substitute_path_command): New function.
        (set_substitute_path_command): New function.
        (_initialize_source): Add new substitute-path commands.

Patch not re-sent, since identical to previous iteration.
See http://sources.redhat.com/ml/gdb-patches/2006-07/msg00062.html.

2006-07-09  Joel Brobecker  <brobecker@adacore.com

        * gdb.texinfo (Source Path): Add documentation for new
        substitute-path commands.

Thanks,
-- 
Joel

[-- Attachment #2: subst-doc.diff --]
[-- Type: text/plain, Size: 3994 bytes --]

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.340
diff -u -p -r1.340 gdb.texinfo
--- gdb.texinfo	21 Jun 2006 13:57:21 -0000	1.340
+++ gdb.texinfo	10 Jul 2006 05:36:05 -0000
@@ -5033,6 +5033,44 @@ To add other directories, use the @code{
 The search path is used to find both program source files and @value{GDBN}
 script files (read using the @samp{-command} option and @samp{source} command).
 
+In addition to the source path, @value{GDBN} provides a set of commands
+that manage a source path substitution rule.  A @dfn{substitution rule}
+specifies how to rewrite source directories stored in the program's
+debug information in case the sources were moved to a different
+directory between compilation and debugging.  The rule is made of
+two strings, the first specifying what needs to be rewritten in
+the path, and the second specifying how it should be rewritten.
+In the @ref{set substitute-path} command description, these two
+parts are named respectively @var{from} and @var{to}.  @value{GDBN}
+does a simple string replacement of the first occurrence of @var{from}
+with @var{to} in the directory part of the source file name, and uses
+the result instead of the original file name to look up the sources.
+
+Using the previous example, suppose the @file{foo-1.0} tree has been
+moved from @file{/usr/src} to @file{/mnt/cross}, then you can tell
+GDB to replace @file{/usr/src} in all source path names with
+@file{/mnt/cross}.  The first lookup will then be
+@file{/mnt/cross/foo-1.0/lib/foo.c} in place of the original location
+of @file{/usr/src/foo-1.0/lib/foo.c}.  To define a source path
+substitution rule, use the @ref{set substitute-path} command.
+
+In many cases, you can achieve the same result using the @code{directory}
+command.  However, @code{set substitute-path} can be more efficient in
+the case where the sources are organized in a complex tree with multiple
+subdirectories.  With the @code{directory} command, you need to add each
+subdirectory of your project.  If you moved the entire tree while
+preserving its internal organization, then @code{set substitute-path}
+allows you to direct the debugger to all the sources with one single
+command.
+
+@code{set substitute-path} is also more than just a shortcut command.
+The source path is only used if the file at the original location no
+longer exists.  On the other hand, @code{set substitute-path} modifies
+the debugger behavior to look at the rewritten location instead.  So, if
+for any reason a source file that is not relevant to your executable is
+located at the original location, the substitution rule is the only
+method available to point GDB at the new location.
+
 @table @code
 @item directory @var{dirname} @dots{}
 @item dir @var{dirname} @dots{}
@@ -5068,6 +5106,34 @@ Reset the source path to its default val
 @item show directories
 @kindex show directories
 Print the source path: show which directories it contains.
+
+@anchor{set substitute-path}
+@item set substitute-path @var{from} @var{to}
+@kindex set substitute-path
+Define a source path substitution rule.  The new substitution rule
+replaces any rule previously defined.
+
+For example, if the file @file{/foo/bar/baz.c} was moved to
+@file{/mnt/cross/baz.c}, then the command
+
+@smallexample
+(@value{GDBP}) set substitute-path /usr/src /mnt/cross
+@end smallexample
+
+@noindent
+will tell @value{GDBN} to replace @samp{/usr/src} with
+@samp{/mnt/cross}, which will allow @value{GDBN} to find the file
+@file{baz.c} even though it was moved.
+
+@item unset substitute-path
+@kindex unset substitute-path
+If a source path substitution rule is active, then cancel it.
+This command has no effect otherwise.
+
+@item show substitute-path
+@kindex show substitute-path
+Print the source path substitution rule if defined.
+
 @end table
 
 If your source path is cluttered with directories that are no longer of

Re: [RFA] New substitute-path commands

[Eli Zaretskii]

> Date: Sun, 9 Jul 2006 22:40:27 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: gdb-patches@sources.redhat.com
> 
> > I suggested to have this text after the command description.  In that
> > context, @var{from} and @var{to} refer to the command's arguments.
> > But you moved the description higher in the text, which made those
> > reference dangling.  So this needs to be reworded in some way.
> 
> You're right. It didn't work that way at all. You'll see my attempt
> at fixing it in this version of the patch.

This version is okay to go in, provided that you fix these small
gotchas:

> +In the @ref{set substitute-path} command description, these two
> +parts are named respectively @var{from} and @var{to}.  @value{GDBN}

@ref needs some punctuation after the closing brace (makeinfo should
have griped about that).  In addition, @ref produces something like
"Section X.YZ [Foo Bar]" in the printed version of the manual, so this
sentence will look awkwardly non-English there ("In the Section X.YZ
[Source Path], p.123 command description, these two...").

So please reword, e.g. like this:

  In @ref{set substitute-path}, we name these two parts @var{from} and
  @var{to}, respectively ...

>                                         To define a source path
> +substitution rule, use the @ref{set substitute-path} command.

Such usage of @ref produces bad results, for the 2nd reason mentioned
above.  You should use @pxref here:

  To define a source path substitution rule, use the @code{set
  substitute-path} command (@pxref{set substitute-path}).

Re: [RFA] New substitute-path commands

[Joel Brobecker]

> This version is okay to go in, provided that you fix these small
> gotchas:

Great! I made the adjustments you suggested, thanks!

Just to be safe, you have approved both documentation and code,
right? I assume this because you also made some comments about
the code, and some of them were technical. I'll commit as soon
as this is confirmed.

It just occurs to me that I should also update the NEWS file. Will do
asap.

Thanks,
-- 
Joel

Re: [RFA] New substitute-path commands

[Daniel Jacobowitz]

On Mon, Jul 10, 2006 at 02:47:06PM -0700, Joel Brobecker wrote:
> > This version is okay to go in, provided that you fix these small
> > gotchas:
> 
> Great! I made the adjustments you suggested, thanks!
> 
> Just to be safe, you have approved both documentation and code,
> right? I assume this because you also made some comments about
> the code, and some of them were technical. I'll commit as soon
> as this is confirmed.

FWIW, this version of the interface is fine with me (I didn't look at
the code).  I strongly agree with Andrew that we should support more
than one substitution rule, but we can do that separately.

-- 
Daniel Jacobowitz
CodeSourcery

Re: [RFA] New substitute-path commands

[Joel Brobecker]

> FWIW, this version of the interface is fine with me (I didn't look at
> the code).  I strongly agree with Andrew that we should support more
> than one substitution rule, but we can do that separately.

I have no problem with that, the interface is extensible in that way.
In terms of implementation, I should have more time for that in the
fall.

-- 
Joel

Re: [RFA] New substitute-path commands

[Daniel Jacobowitz]

On Mon, Jul 10, 2006 at 02:56:30PM -0700, Joel Brobecker wrote:
> > FWIW, this version of the interface is fine with me (I didn't look at
> > the code).  I strongly agree with Andrew that we should support more
> > than one substitution rule, but we can do that separately.
> 
> I have no problem with that, the interface is extensible in that way.
> In terms of implementation, I should have more time for that in the
> fall.

I will hopefully take care of it before then.

-- 
Daniel Jacobowitz
CodeSourcery

Re: [RFA] New substitute-path commands

[Eli Zaretskii]

> Date: Mon, 10 Jul 2006 14:47:06 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: gdb-patches@sources.redhat.com
> 
> Just to be safe, you have approved both documentation and code,
> right?

I did read the code, but I'd prefer that someone else look at it as
well.

Re: [RFA] New substitute-path commands

[Daniel Jacobowitz]

On Thu, Jul 06, 2006 at 10:22:19PM -0700, Joel Brobecker wrote:
> +/* If the user specified a source path substitution rule, then
> +   try applying it on PATH, and return the new path.  This new
> +   path must be deallocated afterwards.
> +   
> +   Return NULL if no substitution rule was specified by the user,
> +   or of this rule didn't apply to the given PATH.  */
> +   
> +static char *
> +xrewrite_source_path (const char *path)

Why the x?  Is it because it allocates?  I believe we actually use the
x to indicate replacements for system functionality which have a more
reliable error behavior; so please don't use it here.

> +  /* Search for the first occurence of SUBSTITUTE_PATH_FROM.
> +     No substitution needed of not found.  */

If not found.

> +  from_start = strstr (path, substitute_path_from);

This is the part of the patch I'm not sure about.  I have two
questions.

1.  Should the substitution rule be anchored to the beginning of the
pathname?

2.  Should the end of the rule be anchored to end of string or
directory separator?

I think #1 should be yes, and #2 should probably be yes, but I'm less
certain about it.  What do you think?

Otherwise the code looks good.

-- 
Daniel Jacobowitz
CodeSourcery

Re: [RFA] New substitute-path commands

[Joel Brobecker]

Hi Daniel,

> > +static char *
> > +xrewrite_source_path (const char *path)
> 
> Why the x?  Is it because it allocates?  I believe we actually use the
> x to indicate replacements for system functionality which have a more
> reliable error behavior; so please don't use it here.

Oops, sorry, misunderstanding on my part. I just removed the x.
I was confused because of xfullpath...

> > +  /* Search for the first occurence of SUBSTITUTE_PATH_FROM.
> > +     No substitution needed of not found.  */
> 
> If not found.

Fixed. Thanks for catching it.

> > +  from_start = strstr (path, substitute_path_from);
> 
> This is the part of the patch I'm not sure about.  I have two
> questions.
> 
> 1.  Should the substitution rule be anchored to the beginning of the
> pathname?
> 
> 2.  Should the end of the rule be anchored to end of string or
> directory separator?
> 
> I think #1 should be yes, and #2 should probably be yes, but I'm less
> certain about it.  What do you think?

  (1): Anchoring means that we replace from the start right, so
       no search within the path, just a strncmp, correct?

       It might be simpler, but on the other hand less flexible.
       I would personally prefer to have it non anchored, but
       it's only a mild preference and I don't know of any
       situation where having the replacement rule anchored
       would cause us any problem in practice.

  (2): I am personally not against this, and it would fit what
       we would do at AdaCore, but I don't see this as a necessary
       constraint that the debugger should check. Again, a mild
       preference.

What do others think? I'm happy to implement whatever the group
thinks is best.

Thanks for the review Daniel,
-- 
Joel

Re: [RFA] New substitute-path commands

[Daniel Jacobowitz]

On Tue, Jul 11, 2006 at 01:30:42PM -0700, Joel Brobecker wrote:
>   (1): Anchoring means that we replace from the start right, so
>        no search within the path, just a strncmp, correct?
> 
>        It might be simpler, but on the other hand less flexible.
>        I would personally prefer to have it non anchored, but
>        it's only a mild preference and I don't know of any
>        situation where having the replacement rule anchored
>        would cause us any problem in practice.
> 
>   (2): I am personally not against this, and it would fit what
>        we would do at AdaCore, but I don't see this as a necessary
>        constraint that the debugger should check. Again, a mild
>        preference.
> 
> What do others think? I'm happy to implement whatever the group
> thinks is best.

The reason for anchoring is to reduce surprising behavior.  Especially
since this only replaces one occurance, it seems like the path of least
astonishment.  For instance, "substitute-path foo bar" would replace
/fool with /barl and /tmp/myfoo with /tmp/mybar.

I'd much prefer (1); I'm ambivalent on (2); whatever anyone prefers is
fine.

-- 
Daniel Jacobowitz
CodeSourcery

Re: [RFA] New substitute-path commands

[Joel Brobecker]

> The reason for anchoring is to reduce surprising behavior.  Especially
> since this only replaces one occurance, it seems like the path of least
> astonishment.  For instance, "substitute-path foo bar" would replace
> /fool with /barl and /tmp/myfoo with /tmp/mybar.

That makes really good sense. I now prefer anchoring too.

Since we're anchoring the start, it might make sense to anchoring
the end as well, if only for consistency.

-- 
Joel

Re: [RFA] New substitute-path commands

[Joel Brobecker]

> 2.  Should the end of the rule be anchored to end of string or
> directory separator?

I was thinking about this, and almost ready to implement it. But
then I thought about the Windows case. On cygwin, the directory
separator is '/', but then some tools probably use '\' and we
accept it. On MinGW, the standard directory separator is '\', but
GCC at least uses forward slashes as far as I know.

So, in implementation terms, anchoring against the directory
separator is tricky on Windows. I think we should accept both.
I'm just not sure what is the best way of implementing this.
Looks like we might not be able to avoid an #ifdef macro.

-- 
Joel

Re: [RFA] New substitute-path commands

[Christopher Faylor]

On Tue, Jul 11, 2006 at 03:25:24PM -0700, Joel Brobecker wrote:
>> 2.  Should the end of the rule be anchored to end of string or
>> directory separator?
>
>I was thinking about this, and almost ready to implement it. But
>then I thought about the Windows case. On cygwin, the directory
>separator is '/', but then some tools probably use '\' and we
>accept it. On MinGW, the standard directory separator is '\', but
>GCC at least uses forward slashes as far as I know.

FWIW, I'm perfectly fine with accepting only '/' on Cygwin but I
doubt that helps much.

cgf

Re: [RFA] New substitute-path commands

[Daniel Jacobowitz]

On Tue, Jul 11, 2006 at 03:25:24PM -0700, Joel Brobecker wrote:
> 
> > 2.  Should the end of the rule be anchored to end of string or
> > directory separator?
> 
> I was thinking about this, and almost ready to implement it. But
> then I thought about the Windows case. On cygwin, the directory
> separator is '/', but then some tools probably use '\' and we
> accept it. On MinGW, the standard directory separator is '\', but
> GCC at least uses forward slashes as far as I know.
> 
> So, in implementation terms, anchoring against the directory
> separator is tricky on Windows. I think we should accept both.
> I'm just not sure what is the best way of implementing this.
> Looks like we might not be able to avoid an #ifdef macro.

Isn't this just IS_DIR_SEPARATOR ?  You probably want to use
FILENAME_CMP too.

The other question is what to do with "C:" on cygwin/mingw32.
I haven't thought about that.  I'd feel free to not worry about it, and
then if it becomes a problem for someone using Windows they can fix
it (which might be me, later - I expect CodeSourcery to want to do the
same thing Andrew Stubbs was talking about and set this up to work
magically).

-- 
Daniel Jacobowitz
CodeSourcery

Re: [RFA] New substitute-path commands

[Joel Brobecker]

> Isn't this just IS_DIR_SEPARATOR ?  You probably want to use
> FILENAME_CMP too.

Yes, you're right. I forgot about the include directory again
when I was searching for this. Since I'm deep into this code,
I think I'll take the time to implement multiple substitution
rules too. I've had so much feedback about this, it's only fair.

> The other question is what to do with "C:" on cygwin/mingw32.
> I haven't thought about that.  I'd feel free to not worry about it, and
> then if it becomes a problem for someone using Windows they can fix
> it (which might be me, later - I expect CodeSourcery to want to do the
> same thing Andrew Stubbs was talking about and set this up to work
> magically).

That works for me. Let's worry about that later if it impacts someone.

Thanks again,
-- 
Joel

Re: [RFA] New substitute-path commands

[Eli Zaretskii]

> Date: Tue, 11 Jul 2006 18:50:19 -0400
> From: Daniel Jacobowitz <drow@false.org>
> Cc: gdb-patches@sources.redhat.com
> 
> The other question is what to do with "C:" on cygwin/mingw32.

If you mean the case that the sources are moved from C:/foo to D:/foo,
then it should be handled, I think.

Re: [RFA] New substitute-path commands

[Daniel Jacobowitz]

On Wed, Jul 12, 2006 at 06:22:40AM +0300, Eli Zaretskii wrote:
> > Date: Tue, 11 Jul 2006 18:50:19 -0400
> > From: Daniel Jacobowitz <drow@false.org>
> > Cc: gdb-patches@sources.redhat.com
> > 
> > The other question is what to do with "C:" on cygwin/mingw32.
> 
> If you mean the case that the sources are moved from C:/foo to D:/foo,
> then it should be handled, I think.

Oh, OK.  Then we can do this the easy way and not worry specially about
drive prefixes, and use IS_ABSOLUTE_PATH.

-- 
Daniel Jacobowitz
CodeSourcery

Re: [RFA] New substitute-path commands

[Joel Brobecker]

> > If you mean the case that the sources are moved from C:/foo to D:/foo,
> > then it should be handled, I think.
> 
> Oh, OK.  Then we can do this the easy way and not worry specially about
> drive prefixes, and use IS_ABSOLUTE_PATH.

In which case would IS_ABSOLUTE_PATH be necessary? I think I'm missing
that case.

-- 
Joel

Re: [RFA] New substitute-path commands

[Daniel Jacobowitz]

On Tue, Jul 11, 2006 at 09:50:18PM -0700, Joel Brobecker wrote:
> > > If you mean the case that the sources are moved from C:/foo to D:/foo,
> > > then it should be handled, I think.
> > 
> > Oh, OK.  Then we can do this the easy way and not worry specially about
> > drive prefixes, and use IS_ABSOLUTE_PATH.
> 
> In which case would IS_ABSOLUTE_PATH be necessary? I think I'm missing
> that case.

Hmm, maybe it isn't.  Ignore me.

-- 
Daniel Jacobowitz
CodeSourcery