xrefrc.txt

emacs的一个非常有用的插件,叫xrefactory,可以实现source insight里的那种函数跳转.和cscope(跳回来不方便)配合使用,非常的不错.

XREFRC(5)                                                            XREFRC(5)



NAME
        .xrefrc - file containing xref options.

DESCRIPTION
       The  ’.xrefrc’  file (’_xrefrc’ under MS-DOS) is configuration file for
       the xref cross-referencing tool. It should be  placed  in  user’s  home
       directory  from  where it is read at each xref invocation (under MS-DOS
       if the %HOME% environment variable is not  set,  this  file  should  be
       placed  in  the  C:\ root folder).  The file contains xref command line
       switches used for processing your projects,  mainly  information  about
       source  files, include directories ( ’-I’ option ) and  default  macro-
       definitions ( ’-D’ option).  It should equally  contain   the   ’-refs’
       option   specifying   where   the  resulting file with cross references
       should be searched or created.  Informations  about  available  options
       can be found in the ’xref’ manual page (’xref.man’ file).

       The  ’.xrefrc’  file  can contain comments starting by two slashes fol-
       lowed by at least one blank character and ending by end of the line.

       Xrefrc file can also contain specification of input  source  files  via
       execution  of an extern command. A command enclosed inside two ‘‘ signs
       is executed and the result of execution (from command’s  standard  out-
       put) is interpreted as a blank separated list of input files. For exam-
       ple, if you wish to process  all files with  .java  suffix  (not  those
       with  .c  suffix) under a given directory (say /usr/src/myproject), you
       can specify (under a Unix system) input files as: ‘find /usr/src/mypro-
       ject -name \*.java -print‘

       Xrefrc  file can also refer environment variables by enclosing variable
       name into ${ and } signs (or between two % % signs). For  example,  you
       can specify the position of a file ’toto’ in your home directory by the
       string "${HOME}/toto". The variable can be either internal  xref  vari-
       able  (which  must  be set by the ’-set <name> <value>’ option), or any
       regular (shell) environment variable, such as  USER,  HOME,  CLASSPATH,
       etc. Also following predefined variables can be used in order to intro-
       duce problematic characters into options: ’pc’ for  percent;  ’dl’  for
       dollar, ’dq’ for double-quotes and ’nl’ for newline (even if newline is
       not really problematic as it can be inside an option enclosed  in  dou-
       ble-quotas).   A  predefined  variable  __BASE  is referring to current
       project name.

       In  order  to  handle multiple projects, ’.xrefrc’ file   is   composed
       from   separate  sections.  Each section starts with a  section  marker
       stating  the project  name.  Options defined inside a section are taken
       into  account if ’xref’ is invoked with the ’-p’ option followed by the
       name of the section.  In  order  to  pass  ’-p’  option  to  xref  from
       Emacs/XEmacs editors, you have to set current project name with the ’M-
       x xref-project-set-active’ function or  by  selecting  it  through  the
       ’Xref->Project->Set Active" menu item.

       There  can  be  options  before the first section marker. Those options
       (not belonging to any project) are common to all projects and are  pro-
       cessed everytime before project specific options.

       Lets  take  for  example  the  ’.xrefrc’  file  defining  two  projects
       (’solver’ and ’player’):

       ---------------------------------------------------------

       [solver]        // first section
       -r /home/marian/solver
       -r /home/marian/commons
       -I /usr/lib/gcc-lib/i386-redhat-linux/2.7.2.3/include
       -DTARGET=linux
       -refs /home/marian/XSrefs
       -htmlroot=/home/marian/HTML

       [player]          // second section
       -r /home/marian/player
       -classpath /usr/share/jdk/classes.zip:/java
       -refs /home/marian/Xplay
       -htmlroot=/home/marian/HTML

       ---------------------------------------------------------

       Invocation via the ’xref -p solver’ command  will  cause  that  (recur-
       sively) all source files from the ’/home/marian/solver’ and ’/home/mar-
       ian/commons’ directories will be cross-referenced.  Also  the  ’TARGET’
       macro  will  be  defined having the value ’linux’. The resulting cross-
       references will be stored into the ’/home/marian/XSrefs’ file.

       An invocation with the ’xref -p player’ command will cause that  source
       files  from  the ’/home/marian/player’ directory will be processed with
       the classpath set to ’/usr/share/jdk/classes.zip:/java’ and the result-
       ing cross-references will be stored in the ’/home/marian/Xplay’ file.

       An  invocation  with the ’xref -html -p player’ command causes that all
       files from the ’/home/marian/player’ directory will be  processed  with
       the  classpath  set  to  ’/usr/share/jdk/classes.zip:/java’,  the input
       files will be converted to the HTML format and the resulting HTML files
       will be stored in a file hierarchy under the ’/home/marian/HTML’ direc-
       tory.

       NOTE: If the ’.xrefrc’ file contains input file names,  they  are  pro-
       cessed  only when invoked with ’-p’ or ’-create’ options on the command
       line.

       NOTE2:  It  is  strongly  recommended  to use all file names within the
       ’.xrefrc’ file with their full absolute paths.


       AUTOMATIC PROJECT DETECTION

       Xrefactory  contains  support  for automatic project detection.  If you
       select  under (X)Emacs ’Xref->Project->Set Active’ and then  you  chose
       "++  Automatic (directory dependent) ++" item, then Xrefactory tries to
       detect active project automatically inferring it from the  place  where
       currently edited file is stored, i.e. from its absolute path.

       Automatic project detection interprets project names as directories and
       a project is activated if its name is a directory containing  (directly
       or  in  several subdirectory levels) the currently edited file (i.e. if
       project name is a prefix of the absolute path of the  currently  edited
       file).   In case that project names overlap, then the most specific one
       (but still covering input file) is selected. In case  that  no  project
       can  be  activated  for  currently  editing  file,  then the last auto-
       detected project remains active.

       For example, let’s take the .xrefrc file:

       ---------------------------------------------------------

       [/home/marian/solver]        // first section
       -I /usr/lib/gcc-lib/i386-redhat-linux/2.7.2.3/include
       -I /home/marian/include
       -I /mygroup/include
       -DTARGET=linux
       -refs /home/marian/XSrefs


       [/home/marian/xref]          // second section
       -I /usr/lib/gcc-lib/i386-redhat-linux/2.7.2.3/include
       -I /home/marian/include
       -I /mygroup/include
       -DNODEBUG
       -refs /home/marian/XXrefs

       ---------------------------------------------------------

       The first part of the file is triggered for all source files with  full
       path name starting by /home/marian/solver directory, the second part is
       triggered for  all  files  under  ’/home/marian/xref’  directory.   For
       example   if   xref   is   invoked  for  a   file,   saying  /home/mar-
       ian/xref/src/main.c this  file  will  be processed  with  options  read
       from the second part.

       When  creating  cross  references  ’xref’ is not able to switch between
       different sections in one single run, continuing our  example,  if  you
       type  the  command  ’xref  -r /home/marian’ then all files will be pro-
       cessed with options from one section of the ’.xrefrc’ file, it  is  not
       defined which section will be taken.


       SHARING SAME OPTIONS IN DIFFERENT PROJECTS

       It  is  possible to define multiple projects sharing same options.  You
       can put several project names separated by ’:’ (’;’  under  MS-Windows)
       inside  section  marker,  i.e.  between [] brackets.  Options following
       such section marker belong to all mentioned projects. Autodetection  of
       project  works  also  for  projects  sharing  same  options. Sharing of
       options is supposed to be used mainly  if  your  project  directory  is
       accessible  also  through  symbolic  links. In this case you can define
       original directory together with it its name through symbolic  link  to
       share same options.  For example, if /dir2 is a symbolic link to /dir1,
       then you will put your options into a project:

       [/dir1:/dir2]
         <projects option>




MULTIPLE PRE-PROCESSOR PASSES
       In the C language the same sources are often  compiled  multiple  times
       with  only  different initial macro settings. Usually the initial macro
       setting is used to remove or to insert parts of source code enclosed in
       #if-#else-#endif  directives.   In  such case the ’#if part’ of code is
       never compiled together with the ’#else part’ of the code. However, for
       the  purpose  of  cross  referencing and (especially) for manipulations
       like renaming, it is essential to put cross-references from both  parts
       together.  For  this  reason  xref  permits  to  define multiple passes
       through source code collecting all references from those  passes.  Usu-
       ally  one  pass corresponds to one possible compilation of sources (for
       example for one possible platform). Multiple passes  are  specified  at
       ’.xrefrc’  file level by using special options ’-pass<n>’, where <n> is
       the pass number. If such an option occurs it causes that all  following
       options  (except other ’-pass’ option) are taken into account only when
       making the <n>-th pass through source code. By default  xref  makes  as
       many  passes through source code as is the greatest <n> used in ’-pass’
       options. For example:


       ---------------------------------------------------------

       [/home/marian/solve]
       -r /home/marian/solve
       -refs /home/marian/XSrefs
       -pass1
       -DTARGET=linux
       -pass2
       -DTARGET=solaris

       ---------------------------------------------------------

       This .xrefrc file causes that all source  files  from  the  ’/home/mar-
       ian/solve’ directory will be processed twice first time with options:

       -r /home/marian/solve
       -refs /home/marian/XSrefs
       -DTARGET=linux

       and second time with options:

       -r /home/marian/solve
       -refs /home/marian/XSrefs
       -DTARGET=solaris

       References  from  both  passes  will be collected and inserted into the
       ’/home/marian/XSrefs’ file.

       NOTE: Multiple passes through sources will increase the  time  of  file
       processing and can considerably slowdown on-line editing actions.


MORE INFO
       http://www.xref-tech.com

SEE ALSO
       xref(1),






                                                                     XREFRC(5)