\input texinfo
@setfilename ../../info/ede
@settitle Emacs Development Environment
+@documentencoding UTF-8
@copying
This file describes EDE, the Emacs Development Environment.
-Copyright @copyright{} 1998-2001, 2004-2005, 2008-2012
+Copyright @copyright{} 1998--2001, 2004--2005, 2008--2014
Free Software Foundation, Inc.
@quotation
@center @titlefont{EDE (The Emacs Development Environment)}
@sp 4
@center by Eric Ludlam
+@page
+@vskip 0pt plus 1filll
+@insertcopying
@end titlepage
@page
@contents
-@node top, EDE Project Concepts, (dir), (dir)
+@node Top, EDE Project Concepts, (dir), (dir)
@top EDE
@comment node-name, next, previous, up
* Building and Debugging:: Initiating a build or debug session.
* Miscellaneous commands:: Other project related commands.
* Extending EDE:: Programming and extending @ede{}.
+* GNU Free Documentation License:: The license for this documentation.
@end menu
-@node EDE Project Concepts, EDE Mode, top, top
+@node EDE Project Concepts, EDE Mode, Top, Top
@chapter @ede{} Project Concepts
@ede{} is a generic interface for managing projects. It specifies a
documentation or interface files. @ede{} can provide this
information.
-@node EDE Mode, Quick Start, EDE Project Concepts, top
+@node EDE Mode, Quick Start, EDE Project Concepts, Top
@chapter @ede{} Mode
@ede{} is implemented as a minor mode, which augments other modes such
commands. These menu items, and their corresponding keybindings, are
independent of the type of project you are actually working on.
-@node Quick Start, Creating a project, EDE Mode, top
+@node Quick Start, Creating a project, EDE Mode, Top
@chapter Quick Start
Once you have @ede{} enabled, you can create a project. This chapter
If your program takes command line arguments, you can type them in
when it offers the command line you want to use to run your program.
-@node Creating a project, Modifying your project, Quick Start, top
+@node Creating a project, Modifying your project, Quick Start, Top
@chapter Creating a project
To create a new project, first visit a file that you want to include
The @command{ede-new} command prompts for the type of project you
would like to create. Each project type has its own benefits or
-language specific enhancements. @ede{} supports four different
-project types: @samp{Make}, @samp{Automake}, @samp{direct Automake},
-and @samp{Simple}.
+language specific enhancements. Not all projects that @ede{} supports
+also allow creating a new project. Projects such as @code{emacs}
+or @code{linux} are designed to recognize existing projects only.
+Project types such as @samp{Make} and @samp{Automake} do support
+creating new project types with @command{ede-new}.
@itemize
@item
@file{Makefile.am} file. @ede{} handles the Automake bootstrapping
routines, which import and maintain a @file{configure.am} script and
other required files.
-
-@item
-For the @samp{direct Automake} project type, @ede{} reads directly
-from the Automake files.
-
-You cannot create direct Automake projects with the @command{ede-new}
-command. Instead, when you visit a project with existing Automake
-files, @ede{} automatically detects them.
-
-@item
-The @samp{Simple} project type provides light-weight constructs for
-identifying a project root and looking up files. If you already have
-a non-@ede{} project infrastructure, you can use a @samp{Simple}
-project to provide other Emacs packages, such as Semantic, with some
-information about the project. @xref{Simple projects}.
@end itemize
A subproject is merely a project in a subdirectory of another project.
the toplevel project handles subprojects in the build process is
dependent on that project's type.
-@node Modifying your project, Building and Debugging, Creating a project, top
+@node Modifying your project, Building and Debugging, Creating a project, Top
@chapter Modifying your project
In this chapter, we describe the generic features for manipulating
To switch between different active configurations, modify the
``configuration default'' slot.
-@node Building and Debugging, Miscellaneous commands, Modifying your project, top
+@node Building and Debugging, Miscellaneous commands, Modifying your project, Top
@chapter Building and Debugging
@ede{} provides the following ``project-aware'' compilation and
These commands are also available from the @samp{Development} menu.
-@node Miscellaneous commands, Extending EDE, Building and Debugging, top
+@node Miscellaneous commands, Extending EDE, Building and Debugging, Top
@chapter Miscellaneous commands
If you opt to go in and edit @ede{} project files directly---for
@node Simple projects
@section Simple Projects
-There is a wide array of Simple projects. The root for simple
-projects is the class @code{ede-simple-project}. This handles the
-infrastructure of storing a .ede file if needed.
-
-The class @code{ede-simple-project} is designed to be subclassed.
-Then key @ede{} methods can be overridden to provide a quick wrapper
-over any project.
+There is a wide array of simple projects. In this case a simple
+project is one that detects, or is directed to identify a directory as
+belonging to a project, but doesn't provide many features of a typical
+@ede{} project. Having the project however allows tools such as
+@semantic{} to find sources and perform project level completions.
-A second project type is @code{ede-cpp-root}. This project type is
-designed to be created for a directory hierarchy full of C/C++ code.
-It can be configured with minimal lisp knowledge to do header file
-lookup for @semantic{}, improving code completion performance.
@menu
* ede-cpp-root:: This project marks the root of a C/C++ code project.
* ede-java-root:: This project marks the root of a Java project.
* ede-emacs:: A project for working with Emacs.
* ede-linux:: A project for working with Linux kernels.
+* ede-generic-project:: A project type for wrapping build systems with EDE.
* Custom Locate:: Customizing how to locate files in a simple project
@end menu
It pre-populates the C Preprocessor symbol map for correct parsing,
and has an optimized include file identification function.
-@node ede-linux, Custom Locate, ede-emacs, Simple projects
+@node ede-linux, ede-generic-project, ede-emacs, Simple projects
@subsection ede-linux
The @code{ede-linux} project will automatically identify a Linux
It pre-populates the C Preprocessor symbol map for reasonable parsing,
and has an optimized include file identification function.
-@node Custom Locate, , ede-linux, Simple projects
+@node ede-generic-project, Custom Locate, ede-linux, Simple projects
+@subsection ede-generic-project
+
+The @code{ede-generic-project} is a project system that makes it easy
+to wrap up different kinds of build systems as an EDE project.
+Projects such as @ref{ede-emacs} require coding skills to create.
+Generic projects also require writing Emacs Lisp code, but the
+requirements are minimal. You can then use
+@command{customize-project} to configure build commands, includes, and
+other options for that project. The configuration is saved in
+@file{EDEConfig.el}.
+
+Generic projects are disabled by default because they have the
+potential to interfere with other projects. To use the generic
+project system to start detecting projects, you need to enable it.
+
+@deffn Command ede-enable-generic-projects
+Enable generic project loaders.
+
+This enables generic loaders for projects that are detected using
+either a @file{Makefile}, @file{SConstruct}, or @file{CMakeLists}.
+
+You do not need to use this command if you create your own generic
+project type.
+@end deffn
+
+If you want to create your own generic project loader, you need to
+define your own project and target classes, and create an autoloader.
+The example for Makefiles looks like this:
+
+@example
+;;; MAKEFILE
+
+(defclass ede-generic-makefile-project (ede-generic-project)
+ ((buildfile :initform "Makefile")
+ )
+ "Generic Project for makefiles.")
+
+(defmethod ede-generic-setup-configuration ((proj ede-generic-makefile-project) config)
+ "Setup a configuration for Make."
+ (oset config build-command "make -k")
+ (oset config debug-command "gdb ")
+ )
+
+(ede-generic-new-autoloader "generic-makefile" "Make"
+ "Makefile" 'ede-generic-makefile-project)
+@end example
+
+This example project will detect any directory with the file
+@file{Makefile} in it as belonging to this project type.
+Customization of the project will allow you to make build and debug
+commands more precise.
+
+@node Custom Locate, , ede-generic-project, Simple projects
@subsection Custom Locate
The various simple project styles all have one major drawback, which
When the EDE API is used to try and file files by some reference name
in the project, then that could fail.
-@@TODO - Add ID Utils and CScope examples
-
@ede{} can therefore use some external locate commands, such as the unix
``locate'' command, or ``GNU Global''.
methods. See the code in @file{ede-locate.el} for GNU Global as a
simple example.
-@node Extending EDE, , Miscellaneous commands, top
+@@TODO - Add ID Utils and CScope examples
+
+More on idutils and cscope is in the CEDET manual, and they each have
+their own section.
+
+@node Extending EDE, GNU Free Documentation License, Miscellaneous commands, Top
@chapter Extending @ede{}
This chapter is intended for users who want to write new parts or fix
is saved, or how a target is compiled can be customized by a project
author in detail. @ede{} communicates to these project objects via an
API using methods. The commands you use in @ede{} mode are high-level
-functional wrappers over these methods. @xref{(eieio)Top}. For
+functional wrappers over these methods. @xref{Top,,, eieio, EIEIO manual}. For
details on using @eieio{} to extending classes, and writing methods.
If you intend to extend @ede{}, it is most likely that a new target type is
override this unless you keep auxiliary files.
@end table
-These methods are used by the semantic package extensions @xref{(semantic)Top}.
+These methods are used by the semantic package extensions.
+@xref{Top,,, semantic, Semantic manual}.
@table @code
@item ede-buffer-header-file
Default Value: @code{"Untitled"}
The name used when generating distribution files.
-@refill
@item :version
Type: @code{string} @*
Default Value: @code{"1.0"}
The version number used when distributing files.
-@refill
@item :directory
Type: @code{string}
Directory this project is associated with.
-@refill
@item :file
Type: @code{string}
File name where this project is stored.
-@refill
@end table
Type: @code{list}
List of top level targets in this project.
-@refill
@item :tool-cache
Type: @code{list}
List of tool cache configurations in this project.
This allows any tool to create, manage, and persist project-specific settings.
-@refill
@item :web-site-url
Type: @code{string} @*
URL to this projects web site.
This is a URL to be sent to a web site for documentation.
-@refill
@item :web-site-directory @*
A directory where web pages can be found by Emacs.
For remote locations use a path compatible with ange-ftp or EFS@.
You can also use TRAMP for use with rcp & scp.
-@refill
@item :web-site-file @*
A file which contains the home page for this project.
This file can be relative to slot @code{web-site-directory}.
This can be a local file, use ange-ftp, EFS, or TRAMP.
-@refill
@item :ftp-site
Type: @code{string} @*
FTP site where this project's distribution can be found.
This FTP site should be in Emacs form, as needed by @code{ange-ftp}, but can
also be of a form used by TRAMP for use with scp, or rcp.
-@refill
@item :ftp-upload-site
Type: @code{string} @*
FTP Site to upload new distributions to.
This FTP site should be in Emacs form as needed by @code{ange-ftp}.
If this slot is @code{nil}, then use @code{ftp-site} instead.
-@refill
@item :configurations
Type: @code{list} @*
List of available configuration types.
Individual target/project types can form associations between a configuration,
and target specific elements such as build variables.
-@refill
@item :configuration-default @*
Default Value: @code{"debug"}
The default configuration.
-@refill
@item :local-variables @*
Default Value: @code{nil}
Project local variables
-@refill
@end table
Default Value: @code{(quote ("/include" "../include/"))}
The default locate function expands filenames within a project.
-If a header file (.h, .hh, etc) name is expanded, and
+If a header file (.h, .hh, etc.)@: name is expanded, and
the @code{:locate-fcn} slot is @code{nil}, then the include path is checked
first, and other directories are ignored. For very large
projects, this optimization can save a lot of time.
that are relative to the project's root should start with a /, such
as "/include", meaning the directory @code{include} off the project root
directory.
-@refill
@item :system-include-path
Type: @code{list} @*
C files initialized in an ede-cpp-root-project have their semantic
system include path set to this value. If this is @code{nil}, then the
semantic path is not modified.
-@refill
@item :spp-table
Type: @code{list} @*
are critical symbols derived from header files. Providing header files
macro values through this slot improves accuracy and performance.
Use `:spp-files' to use these files directly.
-@refill
@item :spp-files
Type: @code{list} @*
The PreProcessor symbols appearing in these files will be used while
parsing files in this project.
See @code{semantic-lex-c-preprocessor-symbol-map} for more on how this works.
-@refill
@item :header-match-regexp
Type: @code{string} @*
Default Value: @code{"\\.\\(h\\(h\\|xx\\|pp\\|\\+\\+\\)?\\|H\\)$\\|\\<\\w+$"}
Regexp used to identify C/C++ header files.
-@refill
@item :locate-fcn
Type: @code{(or null function)} @*
It should return the fully qualified file name passed in from NAME@. If that file does not
exist, it should return nil.
-@refill
@end table
Can be one of @code{'Makefile}, 'Makefile.in, or 'Makefile.am.
If this value is NOT @code{'Makefile}, then that overrides the @code{:makefile} slot
in targets.
-@refill
@item :variables
Type: @code{list} @*
Default Value: @code{nil}
Variables to set in this Makefile.
-@refill
@item :configuration-variables
Type: @code{list} @*
Makefile variables to use in different configurations.
These variables are used in the makefile when a configuration becomes active.
-@refill
@item :inference-rules @*
Default Value: @code{nil}
Inference rules to add to the makefile.
-@refill
@item :include-file @*
Default Value: @code{nil}
Additional files to include.
These files can contain additional rules, variables, and customizations.
-@refill
@item :automatic-dependencies
Type: @code{boolean} @*
Default Value: @code{t}
Non-@code{nil} to do implement automatic dependencies in the Makefile.
-@refill
@item :metasubproject
Type: @code{boolean} @*
projects are grouped into a large project not maintained by EDE, then you need
to set this to non-nil. The only effect is that the @code{dist} rule will then avoid
making a tar file.
-@refill
@end table
Default Value: @code{nil}
Variables to set in this Makefile, at top of file.
-@refill
@item :additional-variables
Type: @code{(or null list)} @*
Arbitrary variables needed from this project.
It is safe to leave this blank.
-@refill
@item :additional-rules
Type: @code{(or null list)} @*
Arbitrary rules and dependencies needed to make this target.
It is safe to leave this blank.
-@refill
@item :installation-domain
Type: @code{symbol} @*
Installation domain specification.
The variable GNUSTEP_INSTALLATION_DOMAIN is set at this value.
-@refill
@item :preamble
Type: @code{(or null list)} @*
The auxiliary makefile for additional variables.
Included just before the specific target files.
-@refill
@item :postamble
Type: @code{(or null list)} @*
The auxiliary makefile for additional rules.
Included just after the specific target files.
-@refill
@item :metasubproject
Type: @code{boolean} @*
projects are grouped into a large project not maintained by EDE, then you need
to set this to non-nil. The only effect is that the @code{dist} rule will then avoid
making a tar file.
-@refill
@end table
Type: @code{string}
Name of this target.
-@refill
@item :path
Type: @code{string}
The path to the sources of this target.
Relative to the path of the project it belongs to.
-@refill
@item :source
Type: @code{list} @*
Default Value: @code{nil}
Source files in this target.
-@refill
@item :versionsource
Type: @code{list} @*
These files are checked for a version string whenever the EDE version
of the master project is changed. When strings are found, the version
previously there is updated.
-@refill
@end table
Type: @code{string}
Name of this target.
-@refill
@item :path
Type: @code{string}
The path to the sources of this target.
Relative to the path of the project it belongs to.
-@refill
@item :auxsource
Type: @code{list} @*
Auxiliary source files included in this target.
Each of these is considered equivalent to a source file, but it is not
distributed, and each should have a corresponding rule to build it.
-@refill
@item :compiler
Type: @code{(or null symbol)} @*
This should be a symbol, which contains the object defining the compiler.
This enables save/restore to do so by name, permitting the sharing
of these compiler resources, and global customization thereof.
-@refill
@item :linker
Type: @code{(or null symbol)} @*
This should be a symbol, which contains the object defining the linker.
This enables save/restore to do so by name, permitting the sharing
of these linker resources, and global customization thereof.
-@refill
@end table
Default Value: @code{"Makefile"}
File name of generated Makefile.
-@refill
@item :partofall
Type: @code{boolean} @*
Non @code{nil} means the rule created is part of the all target.
Setting this to @code{nil} creates the rule to build this item, but does not
include it in the ALL`all:' rule.
-@refill
@item :configuration-variables
Type: @code{list} @*
These variables are used in the makefile when a configuration becomes active.
Target variables are always renamed such as foo_CFLAGS, then included into
commands where the variable would usually appear.
-@refill
@item :rules
Type: @code{list} @*
Arbitrary rules and dependencies needed to make this target.
It is safe to leave this blank.
-@refill
@end table
prefix, or a ".so" suffix.
Note: Currently only used for Automake projects.
-@refill
@item :ldflags
Type: @code{list} @*
options to the linker.
Note: Not currently used. This bug needs to be fixed.
-@refill
@end table
There should only be one toplevel package per auxiliary tool needed.
These packages location is found, and added to the compile time
load path.
-@refill
@end table
The file that autoload definitions are placed in.
There should be one load defs file for a given package. The load defs are created
for all Emacs Lisp sources that exist in the directory of the created target.
-@refill
@item :autoload-dirs
Type: @code{list} @*
The directories to scan for autoload definitions.
If @code{nil} defaults to the current directory.
-@refill
@end table
Miscellaneous sources which have a specialized makefile.
The sub-makefile is used to build this target.
-@refill
@end table
The main menu resides in this file.
All other sources should be included independently.
-@refill
@end table
Default Value: @code{"guile"}
The preferred interpreter for this code.
-@refill
@end table
Default Value: @code{nil}
Additional LD args.
-@refill
@end table
@end table
Default Value: @code{nil}
Additional texinfo included in this one.
-@refill
@end table
@end table
The parent of this instance.
If a slot of this class is reference, and is unbound, then the parent
is checked for a value.
-@refill
@item :name
Type: @code{string}
The name of this type of source code.
Such as "C" or "Emacs Lisp"
-@refill
@item :sourcepattern
Type: @code{string} @*
Default Value: @code{".*"}
Emacs regex matching sourcecode this target accepts.
-@refill
@item :auxsourcepattern
Type: @code{(or null string)} @*
Emacs regex matching auxiliary source code this target accepts.
Aux source are source code files needed for compilation, which are not compiled
themselves.
-@refill
@item :enable-subdirectories
Type: @code{boolean} @*
If sourcecode always lives near the target creating it, this should be nil.
If sourcecode can, or typically lives in a subdirectory of the owning
target, set this to t.
-@refill
@item :garbagepattern
Type: @code{list} @*
Shell file regex matching files considered as garbage.
This is a list of items added to an @code{rm} command when executing a @code{clean}
type directive.
-@refill
@end table
The parent of this instance.
If a slot of this class is reference, and is unbound, then the parent
is checked for a value.
-@refill
@item :name
Type: @code{string}
Name of this type of compiler.
-@refill
@item :variables
Type: @code{list}
An assoc list where each element is (VARNAME . VALUE) where VARNAME
is a string, and VALUE is either a string, or a list of strings.
For example, GCC would define CC=gcc, and emacs would define EMACS=emacs.
-@refill
@item :sourcetype
Type: @code{list}
A list of @code{ede-sourcecode} @xref{ede-sourcecode}. objects this class will handle.
This is used to match target objects with the compilers and linkers
they can use, and which files this object is interested in.
-@refill
@item :rules
Type: @code{list} @*
Auxiliary rules needed for this compiler to run.
For example, yacc/lex files need additional chain rules, or inferences.
-@refill
@item :commands
Type: @code{list}
The commands used to execute this compiler.
The object which uses this compiler will place these commands after
it's rule definition.
-@refill
@item :autoconf
Type: @code{list} @*
call to initialize automake to use this compiler.
For example, there may be multiple C compilers, but they all probably
use the same autoconf form.
-@refill
@item :objectextention
Type: @code{string}
A string which is the extension used for object files.
For example, C code uses .o on unix, and Emacs Lisp uses .elc.
-@refill
@end table
The parent of this instance.
If a slot of this class is reference, and is unbound, then the parent
is checked for a value.
-@refill
@item :name
Type: @code{string}
Name of this type of compiler.
-@refill
@item :variables
Type: @code{list}
An assoc list where each element is (VARNAME . VALUE) where VARNAME
is a string, and VALUE is either a string, or a list of strings.
For example, GCC would define CC=gcc, and emacs would define EMACS=emacs.
-@refill
@item :sourcetype
Type: @code{list}
A list of @code{ede-sourcecode} @xref{ede-sourcecode}. objects this class will handle.
This is used to match target objects with the compilers and linkers
they can use, and which files this object is interested in.
-@refill
@item :commands
Type: @code{list}
The commands used to execute this compiler.
The object which uses this compiler will place these commands after
it's rule definition.
-@refill
@item :objectextention
Type: @code{string}
A string which is the extension used for object files.
For example, C code uses .o on unix, and Emacs Lisp uses .elc.
-@refill
@item :makedepends
Type: @code{boolean} @*
Default Value: @code{nil}
Non-@code{nil} if this compiler can make dependencies.
-@refill
@item :uselinker
Type: @code{boolean} @*
Non-@code{nil} if this compiler creates code that can be linked.
This requires that the containing target also define a list of available
linkers that can be used.
-@refill
@end table
Type: @code{list}
A variable dedicated to dependency generation.
-@refill
@end table
@end table
Type: @code{string}
Name of this type of compiler.
-@refill
@item :variables
Type: @code{list}
An assoc list where each element is (VARNAME . VALUE) where VARNAME
is a string, and VALUE is either a string, or a list of strings.
For example, GCC would define CC=gcc, and emacs would define EMACS=emacs.
-@refill
@item :sourcetype
Type: @code{list}
A list of @code{ede-sourcecode} @xref{ede-sourcecode}. objects this class will handle.
This is used to match target objects with the compilers and linkers
they can use, and which files this object is interested in.
-@refill
@item :commands
Type: @code{list}
The commands used to execute this compiler.
The object which uses this compiler will place these commands after
it's rule definition.
-@refill
@item :objectextention
Type: @code{string}
A string which is the extension used for object files.
For example, C code uses .o on unix, and Emacs Lisp uses .elc.
-@refill
@end table
@end table
+@node GNU Free Documentation License, , Extending EDE, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
@bye