xref.txt

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

XREF(1)                                                                XREF(1)



NAME
       xref - A cross referencing tool for C and Java.

SYNOPSIS
       xref   [options] infile [... infile]

TYPICAL INVOCATION FORMS
       xref   -p <project>

       xref   -update -p <project>

       xref   -html -p <project>

       xref   -update -html -p <project>


       xref   <srcdir>

       xref   -html <srcdir>

DESCRIPTION
       Xref  is  a  C and Java cross-referencing tool.  It parses input
       files noting all symbol’s definitions and usages. If not invoked
       with  the -html option its output is a list of symbols, together
       with positions of declarations, definition and all usages.  Out-
       put is written to the file specified by the -refs option. Xref’s
       cross references are destinated to be read by xref itself or  by
       on-line  editing  macros. Programming language in which an input
       file is written is inferred from file suffix as  follows:  .java
       for a Java language file, .y for a YACC (and C) input file, .jar
       for a Java archive file and finally all other suffixes  are  in-
       terpreted as C input files.

       When  invoked  with  the -html option xref  does not produce the
       cross reference file. Instead it reads an existing cross  refer-
       ence  file  and  then it converts input files into a HTML format
       browsable by standard Internet browsers.  In  those  files  each
       symbol  is  linked  to its definition.  If options ’-htmlgxlist’
       and ’-htmllxlist’ is present then each definition is linked to a
       list  of all symbol usages.  HTML files are written in directory
       hierarchy specified by the -htmlroot option.


WILD CHARACTERS
       Following wild characters can  be  used  when  specifying  input
       files:  ’*’  expands to any (possibly empty) string; ’?’ expands
       to any single character and ’[...]’ pair expands to one  of  en-
       closed  characters. Ranges of characters can be included between
       [ and ], so for example [a-z] matches  any  lower  case  letter,
       [0-9]  matches  any  digit, as it is usual in standard shell ex-
       pressions. If the first character following the [ is  a  ^  then
       the  sense  of expansion is inversed, for example [^0-9] expands
       to any non-digit character. Options -I, -classpath,  -sourcepath
       and  -javadocpath  also accept wild characters. Be carefull when
       using wild characters in those options as they can  considerably
       slow down the task.


NOTE
       Xref  accepts  many options, however except the -p , -update and
       -html options, it is not recommended to write them  directly  on
       the  command  line.  The standard way of passing options to xref
       is configuration file named .xrefrc placed in user’s home direc-
       tory.  Options  stored  in  the ${HOME}/.xrefrc file are read at
       each xref invocation. Storing command  line  options  into  this
       file  is the only way how you can pass project depending options
       to xref when invoked from Emacs.

       Order of options on command line is important. Options are  pro-
       cessed in order in which they are written.


OPTIONS
       Here is the table of command options accepted by xref.

       -p project
              At  the  beginning of the execution, read and process op-
              tions from the section project of the .xrefrc  configura-
              tion  file. This option is used to abstract from concrete
              options and file names when using xref from command  line
              and  from  several  IDEs.  For more info, see the .xrefrc
              file documentation.

       -r     This option is default now, so you do not need  to  enter
              it.   It  causes that if a directory is entered as infile
              then all files from the directory having the suffix  ’.c’
              or ’.java’ are processed (note that it is useless to pro-
              cess the ’.h’ suffixes as they are processed when includ-
              ed  by  a  ’.c’  file).   Subdirectories  are recursively
              searched. This option is obsolete now.

       --r    Do not process directories recursively. This  is  inverse
              option to -r option.

       -prune paths
              When  recursively  searching for input files do not enter
              into directories in paths. Paths can be either  a  simple
              name,  an  absolute path, or a ’:’ (’;’ under MS-Windows)
              separated   list   of   both.    For    example    -prune
              CVS:/project/backup will forbids scanning of the directo-
              ry /project/backup as well as all directories named  CVS.

       -I dir Add  the  directory dir to the end of list of directories
              inspected when looking for an include file.  If specified
              more than one ‘-I’ option, the directories are scanned in
              left-to-right order. If the directory is specified  using
              relative path, it is considered relative to the currently
              parsed file directory.

       -Dname  Predefine name as a macro, with definition ‘1’.

       -Dname=definition
               Predefine name as a macro, with definition definition.

       -resetIncludeDirs
              This option removes all directories from include directo-
              ry  list  (including the default include directories like
              /usr/include).  This option should be used before any  -I
              option.

       -cacheincludes
              This  option  causes  that xref task will keep readed in-
              clude files in memory and reuse them when processing next
              files.   This  can  improve  time  performance  when many
              source files are using common header files. Especially if
              those  header  files are read over network or from a slow
              drive. It will increase space requirements, however.

       -jdkclasspath paths
              This option defines  path  to  standard  runtime  library
              (rt.jar)  of your Java installation. If you are using JDK
              from Sun Microsystems, then xref task should be  able  to
              infer this path from PATH and JAVA_HOME environment vari-
              ables. Otherwise you will need to specify  it  explicitly
              using  -jdkclasspath  option.  The syntax of paths is the
              same as for the -classpath option.  For example  you  can
              use          the          ’-jdkclasspath         /usr/lo-
              cal/jdk1.2.2/jre/lib/rt.jar’ settting for most  Java  1.2
              installations.

       -classpath paths
              This option specifies the classpath used for finding Java
              .class files.  This option overrides the value of the en-
              vironment  variable  CLASSPATH.  See also the ’-jdkclass-
              path’ and ’-sourcepath’ option.

       -sourcepath paths
              This option specifies paths where sources of  Java  pack-
              ages  and classes are searched. This option overrides the
              value of the environment  variable  SOURCEPATH.   If  not
              present  the  current  classpath  is used as default. The
              ’sourcepath’ value is used for finding  source  files  in
              the  same  way  as ’classpath’ is used for finding .class
              compiled files.  When loading a class having both  source
              and class available then the time of last modification of
              both files is examined and the class is loaded  from  the
              newer file.

       -javadocpath=<path>
              Specifies  paths where Javadoc documentation is stored in
              local file system. Several paths can  be  specified,  the
              syntax  is  the same as for classpath value. When looking
              for a javadoc documentation, xref will first search files
              on  paths specified by -javadocpath, if not found and the
              package documentation is available (-javadocavailable op-
              tion) the URL specified by -javadocurl is taken.  See al-
              so -javadocurl, -javadocavailable and -htmlgenjavadoclink
              options.

       -packages
              This  option allows to enter package names instead of in-
              put file names on command line.

       -source <version>
              Specifies version of Java in which sources  are  written.
              Currently  available values are: "1.3", "1.4" and "auto".
              Version "auto" will cause that xref determines Java  ver-
              sion  automatically  from  Java  runtime library. Version
              "1.4" means that ’assert’ command is allowed and ’assert’
              string  is  considered  as keyword, so you can’t have any
              method or variable of this name. Default value is  "1.3".

       -java1.4
              This  option is obsolete, use -source instead.  With this
              option sources are considered to be written in Java  ver-
              sion 1.4 (or higher).

       -refs file
              This option specifies the file where the cross-references
              are stored. If the -refnum=n option is present  then  the
              file  indicates the directory where cross-reference files
              are stored.

       -refnum=<number>
              This option specifies how many cross reference files will
              be  generated.  When <number> == 1, the name specified by
              the ’-refs’ option is directly the name of the cross ref-
              erence  file.   When <number> > 1 then the name specified
              by the ’-refs’ option is interpreted as  directory  where
              cross reference files are stored.  You should specify the
              <number> proportionally to the size of your project.   Do
              not  forget to delete the old cross-reference file if you
              change the -refnum from 1 to a bigger value.

       -refalphahash
              Split references into 28 files  depending  on  the  first
              letter of the symbol. This option is useful when generat-
              ing HTML form, because it makes easy to find cross refer-
              ences  for given symbol name.  This option excludes using
              of the -refnum option.

       -refalpha2hash
              Split references into 28*28 files depending on the  first
              two  letters  of  the  symbol. This option is useful when
              generating HTML form, because it makes easy to find cross
              references  for  given symbol name.  This option excludes
              using of the -refnum option.

       -exactpositionresolve
              This option controls how symbols which  are  local  to  a
              compilation  unit, but usually used in several files, are
              linked together.  This concerns C language  symbols  like
              macros,  structures and their records, etc.  Such symbols
              have no link names passed to linker  (like  global  func-
              tions  have).  This creates a problem how ’xref’ can link
              together (for example) structures of the same  name  used
              in different compilation units.  If the -exactpositionre-
              solve option is present then such symbols are  considered
              to  be  equals  if  their  definitions come from the same
              header file and they are defined at the same position  in
              the  file  (in other words if this is a single definition
              in the source code). Otherwise two symbols are linked to-
              gether  when  they  have the same name.  The ’-exactposi-
              tionresolve’ is very powerful feature because  it  allows
              perfect  resolution  of  browsed symbol and allows you to
              safely rename one of two symbols if a name  conflict  oc-
              curs.  However this option also causes that you will need
              to update cross reference file after each modification of
              a  header file (as the cross-reference file stores infor-
              mation about position of the macro definition).  Updating
              may  be  too  annoying  in normal use when you often edit
              header files.  In general,  this  option  is  recommended
              when  browsing  source code which is not under active de-
              velopment.


       -noincluderefresh
              This is a particular option importing only when xref task
              is used from Emacs. It causes that xref task does not up-
              date include references when used by an Emacs macro. This
              avoids  memory overflow for huge projects or for projects
              including huge header files (for example  when  including
              Microsoft windows API headers).


       -update
              This option represents standard way of how to keep cross-
              reference file up to date. It  causes  that  modification
              time  of  all  input files as well as those listed in the
              existing cross-reference file are checked and only  those
              having newer modification time than existing cross-refer-
              ence file are scheduled to be processed. Also  all  files
              which  includes  (by  Cpp  pre-processor) those files are
              scheduled to be processed.

       -fastupdate
              The same as -update with the difference that files  which
              include modified files are not scheduled to be processed.
              Unless you are using also ’-exactpositionresolve’  option
              this is enough for most references to be correctly updat-
              ed.

       -fastupdate
              Fast update, force update of input files. This option  is
              like  the  -update  option with the difference that input
              files entered on command line are  always  reparsed  (not
              depending on their modification time).

       -set <name> <value>
              The  xref  task  provide a simple environment management.
              The -set option  associates  the  string  <name>  to  the
              string <value>. The value can be then accessed by enclos-
              ing the name in ${ }.

              If an option contains name of previously defined variable
              enclosed  in  ${  and }, then the name (together with en-
              colsing ${}) is  replaced  by  the  corresponding  value.
              Variables  can  be hence used to abbreviate options or to
              predefine repeated parts of  options.   Following  prede-
              fined  variables  can be used in order to introduce prob-
              lematic characters into options: ’nl’ for  newline;  ’pc’
              for  percent; ’dl’ for dollar and ’dq’ for double-quotes.
              Also all environment variables taken from operating  sys-
              tem  (like  PATH,  HOME,  ...) are ’inherited’ and can be