Hi Richard,
Thanks for looking at this. Comments inline below...
On 09/07/2010 12:32 AM, Richard Kim wrote:
> I would like to ask some questions by way of a diff against the texinfo
> files.
>
> One suggested change to explain "/include" syntax is also included.
> I used 20 line context by specifying "-U 20" hoping that that would
> provide sufficient context to orient the readers properly.
>
> Can someone answer my questions?
> Thanks.
>
>
>
> $ bzr diff --diff-opt='-U 20'
> === modified file 'ede/ede.texi'
> --- ede/ede.texi 2010-07-25 14:12:32 +0000
> +++ ede/ede.texi 2010-09-07 04:03:55 +0000
> @@ -569,58 +569,86 @@
> @code{ede-cpp-root-project} and add your own tweaks in just a few
> lines. See the end of this file for an example.
>
> In the most basic case, add this to your @file{.emacs} file, modifying
> appropriate bits as needed.
>
> @example
> (ede-cpp-root-project "SOMENAME" :file "/dir/to/some/file")
> @end example
>
> Replace @var{SOMENAME} with whatever name you want, and the filename
> to an actual file at the root of your project. It might be a
> Makefile, a README file. Whatever. It doesn't matter. It's just a
> key to hang the rest of @ede{} off of.
>
> The most likely reason to create this project, is to speed up
> searching for includes files, or to simplify bootstrapping @semantic{}'s
> ability to find files without much user interaction. In conjunction
> with @semantic{} completion, having a short include path is key. You can
> override the default include path and system include path like this:
> +@c What is the ``default include path''?
There is a default project include path, and a default system include
path. The default project include path is:
( "/include" "../include/" )
and can be found with:
C-h v ede-cpp-root-project RET
The default system path is defined by the variable
semantic-dependency-system-include-path. EDE actually augments this
list and does not override it.
> @example
> (ede-cpp-root-project "NAME" :file "FILENAME"
> :include-path '( "/include" "../include" "/c/include" )
> :system-include-path '( "/usr/include/c++/3.2.2/" )
> :spp-table '( ("MOOSE" . "")
> ("CONST" . "const") ) )
> @end example
>
> In this case each item in the include path list is searched. If the
> -directory starts with "/", then that expands to the project root
> -directory. If a directory does not start with "/", then it is
> -relative to the default-directory of the current buffer when the file
> +directory starts with "/", it does not mean start of absolute path.
> +Instead it means ``relative to the project root
> +directory'', i.e., ``/include'' means ``include'' subdirectory of the
> +project root directory. If a directory does not start with "/", then it is
> +relative to the @var{default-directory} of the current buffer when the file
> name is expanded.
>
> The include path only affects C/C++ header files. Use the slot
> @code{:header-match-regexp} to change it.
>
> +@c I can guess that directories listed in :include-path are searched for files
> +@c whose name matches the regexp specified by :header-match-regexp.
> +@c What is the significance of the match? For gcc we know what it means to
> +@c add -I/a/b/c. For gcc you never have to worry about other implementation
> +@c files when you are compiling a file; you only care about relevant header
> +@c files. For EDE and semantic however that is not the case or so it seems to
> +@c me. We care about
> +@c header and implementation files equally since we are looking for symbols of
> +@c interest for semantic wherever they may be. So what does it mean to be part of
> +@c :include-path? Does it mean that clicking on lines with #include will do
> +@c the ``right thing'' whatever that means?
This is used for something else. In EDE, there is a single
"ede-expand-filename". You can pass it any file. For most projects, if
you pass it "foo.h", it will search everything for it. For this
project, if it thinks foo.h is a header, it will search the project
include path first, theoretically speeding up the time it takes to find
the file.
Thus, it is just an optimization.
> +@c If I just want to tell semantic that all files in this and that directories
> +@c are part of the same project and all C/C++ files in those directories
> +@c (whether or not they are header or implementation files) are to be included
> +@c when I execute command such as semantic-complete-jump, then how do I do
> +@c that? I don't understand why one would ever want to distinguish between
> +@c header and implementation files for semantic other than dealing with
> +@c #include tags.
> +@c
> +@c If a project has deep subdirectory hierarchy, then it would be awkward to
> +@c have to list all the subdirectories with :include-path.
> +@c Is there a way to tell EDE to use a directory and all subdirectories
> +@c under it going down recursively?
> +
In this case, the preferred thing is to use some other project scheme,
such as Automake, or to create a new project type for that build system
which would be able to infer this information.
ede-cpp-root is for the case where no existing project style works.
So yes, it is a pain. The solution is to have better project styles.
Anyway, if some .h is not in the include path, and you use a tool like
GNU Global and associate that with your project, then if a header is not
in an include directory, it will find it anyway, so you don't need to
add everything to the include path in that case.
> The @code{:system-include-path} allows you to specify full directory
> names to include directories where system header files can be found.
> These will be applied to files in this project only.
>
> The @code{:spp-table} provides a list of project specific #define
> style macros that are unique to this project, passed in to the
> compiler on the command line, or are in special headers.
> See the @code{semantic-lex-c-preprocessor-symbol-map} for more
> on how to format this entry.
>
> If there is a single file in your project, you can instead set the
> @code{:spp-files} to a list of file names relative to the root of your
> project. Specifying this is like setting the variable
> @code{semantic-lex-c-preprocessor-symbol-file} in semantic.
>
> If you want to override the file-finding tool with your own
> function you can do this:
>
> @example
> (ede-cpp-root-project "NAME" :file "FILENAME" :locate-fcn 'MYFCN)
>
> === modified file 'semantic/doc/user-guide.texi'
> --- semantic/doc/user-guide.texi 2010-06-13 01:19:18 +0000
> +++ semantic/doc/user-guide.texi 2010-09-07 04:15:29 +0000
> @@ -1794,40 +1794,44 @@
> You can test the interruptibility framework by running
> @kbd{M-x semantic-test-throw-on-input RET} and seeing that you can
> press any key to break out of the loop.
>
> @section Incremental parsing
>
> The incremental parser used by semantic will reparse only small
> sections of a file you have edited, which eliminates the need to
> reparse entire files. This speeds up minor modes that need the local
> buffer to be up to date, such as speedbar or ECB.
>
> If the incremental parsing is not always working for you (meaning it
> will parse the whole file frequently while you edit) then perhaps you
> need to customize @code{semantic-edits-verbose-flag} to enable some
> friendly debug output. Additionally using
> @code{semantic-load-enable-semantic-debugging-helpers} to help
> identify possible problem areas by enabling highlight edits mode and
> show parser state mode
> @inforef{Incremental Parser Debugging, ,semantic-langdev.info}
>
> +@c This is all good, but what if I want the other extreme where I want all
> +@c files in the project (regardless which directory they are in) to be parsed
> +@c that have not yet been parsed? Is there a command for it?
There is a shell script semanticdb.sh that can do that in a script if
you wish to invoke it by hand, or in your Makefile.
I haven't done this by default because the code I work on at work would
crash Emacs if I parsed that many source files. In addition, I've found
that in a majority of cases, typical use cases all work fine with the
subset of parsed files, and you can expand with GNU Global or CScope if
you want the whole project searchable in one go, which I have found to
be much faster and "good enough" for most cases.
Good Questions!
Eric
|