@copying
This file describes EDE, the Emacs Development Environment.
-Copyright @copyright{} 1998-2001, 2004-2005, 2008-2011 Free Software Foundation, Inc.
+Copyright @copyright{} 1998--2001, 2004--2005, 2008--2013
+Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
is included in the section entitled ``GNU Free Documentation License.''
(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
-modify this GNU manual. Buying copies from the FSF supports it in
-developing GNU and promoting software freedom.''
+modify this GNU manual.''
@end quotation
@end copying
@contents
-@node top, EDE Project Concepts, (dir), (dir)
+@node Top, EDE Project Concepts, (dir), (dir)
@top EDE
@comment node-name, next, previous, up
@menu
* EDE Project Concepts:: @ede{} Project Concepts
* EDE Mode:: Turning on @ede{} mode.
+* Quick Start:: Quick start to building a project.
* Creating a project:: Creating a project.
* Modifying your project:: Adding and removing files and targets.
* Building and Debugging:: Initiating a build or debug session.
* Miscellaneous commands:: Other project related commands.
-* Simple projects:: Projects not managed by @ede{}.
* 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, Creating a project, 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 Creating a project, Modifying your 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
+provides an example C++ project that will create Automake files for
+compilation.
+
+@section Step 1: Create root directory
+
+First, lets create a directory for our project. For this example,
+we'll start with something in @file{/tmp}.
+
+@example
+C-x C-f /tmp/myproject/README RET
+M-x make-directory RET RET
+@end example
+
+Now put some plain text in your README file to start.
+
+Now, lets create the project:
+
+@example
+M-x ede-new RET Automake RET myproject RET
+@end example
+
+
+Nothing visible happened, but if you use @code{dired} to look at the
+directory, you should see this:
+
+@example
+ /tmp/myproject:
+ total used in directory 32 available 166643476
+ drwxr-xr-x 2 zappo users 4096 2012-02-23 22:10 .
+ drwxrwxrwt 73 root root 20480 2012-02-23 22:10 ..
+ -rw-r--r-- 1 zappo users 195 2012-02-23 22:10 Project.ede
+ -rw-r--r-- 1 zappo users 10 2012-02-23 22:09 README
+@end example
+
+@section Step 2: Create Subdirectories and Files
+
+We'll make a more complex project, so use dired to create some more
+directories using the @kbd{+} key, and typing in new directories:
+
+@example
++ include RET
++ src RET
+@end example
+
+Now I'll short-cut in this tutorial. Create the following files:
+
+@file{include/myproj.hh}
+@example
+/** myproj.hh ---
+ */
+
+#ifndef myproj_hh
+#define myproj_hh 1
+
+#define IMPORTANT_MACRO 1
+
+int my_lib_function();
+
+#endif // myproj_hh
+@end example
+
+
+@file{src/main.cpp}
+@example
+/** main.cpp ---
+ */
+
+#include <iostream>
+#include "myproj.hh"
+
+int main() @{
+
+@}
+
+#ifdef IMPORTANT_MACRO
+int my_fcn() @{
+
+@}
+#endif
+@end example
+
+@file{src/mylib.cpp}
+@example
+/** mylib.cpp ---
+ *
+ * Shared Library to build
+ */
+
+int my_lib_function() @{
+
+@}
+@end example
+
+@section Step 3: Create subprojects
+
+@ede{} needs subdirectories to also have projects in them. You can
+now create those projects.
+
+With @file{main.cpp} as your current buffer, type:
+
+@example
+M-x ede-new RET Automake RET src RET
+@end example
+
+and in @file{myproj.hh} as your current buffer, type:
+
+@example
+M-x ede-new RET Automake RET include RET
+@end example
+
+These steps effectively only create the Project.ede file in which you
+will start adding targets.
+
+@section Step 4: Create targets
+
+In order to build a program, you must have targets in your @ede{}
+Projects. You can create targets either from a buffer, or from a
+@code{dired} directory buffer.
+
+Note: If for some reason a directory list buffer, or file does not have the
+@samp{Project} menu item, or if @ede{} keybindings don't work, just
+use @kbd{M-x revert-buffer RET} to force a refresh. Sometimes
+creating a new project doesn't restart buffers correctly.
+
+Lets start with the header file. In @file{include/myproj.hh}, you
+could use the menu, but we will now start using the @ede{} command prefix
+which is @kbd{C-c .}.
+
+@example
+C-c . t includes RET miscellaneous RET y
+@end example
+
+
+This creates a misc target for holding your includes, and then adds
+myproj.hh to the target. Automake (the tool) has better ways to do
+this, but for this project, it is sufficient.
+
+Next, visit the @file{src} directory using dired. There should be a
+@samp{Project} menu. You can create a new target with
+
+@example
+. t myprogram RET program RET
+@end example
+
+Note that @kbd{. t} is a command for creating a target. This command
+is also in the menu. This will create a target that will build a
+program. If you want, visit @file{Project.ede} to see the structure
+built so far.
+
+Next, place the cursor on @file{main.cpp}, and use @kbd{. a} to add
+that file to your target.
+
+@example
+. a myprogram RET
+@end example
+
+Note that these prompts often have completion, so you can just press
+@kbd{TAB} to complete the name @file{myprogram}.
+
+If you had many files to add to the same target, you could mark them
+all in your dired buffer, and add them all at the same time.
+
+Next, do the same for the library by placing the cursor on @file{mylib.cpp}.
+
+@example
+. t mylib RET sharedobject RET
+. a mylib RET
+@end example
+
+@section Step 5: Compile, and fail
+
+Next, we'll try to compile the project, but we aren't done yet, so it
+won't work right away.
+
+Visit @file{/tmp/myproject/Project.ede}. We're starting here because
+we don't have any program files in this directory yet. Now we can use
+the compile command:
+
+@example
+C-c . C
+@end example
+
+Because this is the very first time, it will create a bunch of files
+for you that are required by Automake. It will then use automake to
+build the support infrastructure it needs. This step is skipped if
+you choose just a @file{Makefile} build system.
+
+After the Automake init, it runs compile. You will immediately
+discover the error in main.cpp can't find @file{myproj.hh}. We need
+to go fix this.
+
+@section Step 6: Customizing your project
+
+To fix the failed compile, we need to add
+@file{/tmp/myproject/include} to the include path.
+
+Visit @file{main.cpp}.
+
+@example
+M-x customize-project RET
+@end example
+
+Select the @samp{[Settings]} subgroup of options. Under
+@samp{Variable :} click @samp{[INS]}. At this point, you need to be
+somewhat savvy with Automake. Add a variable named @samp{CPPFLAGS},
+and set the value to @samp{../include}.
+
+You should see something like this:
+
+@example
+Variables :
+[INS] [DEL] Cons-cell:
+ Name: AM_CPPFLAGS
+ Value: -I../include
+[INS]
+Variables to set in this Makefile.
+@end example
+
+Click @samp{[Apply]}. Feel free to visit @file{Project.ede} to see
+how it changed the config file.
+
+Compile the whole project again with @kbd{C-c . C} from
+@file{main.cpp}. It should now compile.
+
+@section Step 7: Shared library dependency
+
+Note: Supporting shared libraries for Automake in this way is easy,
+but doing so from a project of type Makefile is a bit tricky. If you
+are creating shared libraries too, stick to Automake projects.
+
+Next, lets add a dependency from @file{main.cpp} on our shared
+library. To do that, update main like this:
+
+@example
+int main() @{
+
+ my_lib_function();
+
+@}
+@end example
+
+Now compile with:
+
+@example
+C-c . c
+@end example
+
+where the lower case @kbd{c} compiles just that target. You should
+see an error.
+
+This time, we need to add a dependency from @file{main.cpp} on our shared
+library. To do that, we need to customize our target instead of the
+project. This is because variables such as the include path are
+treated globally, whereas dependencies for a target are target specific.
+
+@example
+M-x customize-target RET
+@end example
+
+On the first page, you will see an Ldlibs-local section. Add mylib to
+it by first clicking @samp{[INS]}, and they adding the library. It
+should look like this:
+
+@example
+Ldlibs-Local :
+[INS] [DEL] Local Library: libmylib.la
+[INS]
+Libraries that are part of this project. [Hide Rest]
+The full path to these libraries should be specified, such as:
+../lib/libMylib.la or ../ar/myArchive.a
+@end example
+
+You will also see other variables for library related flags and system
+libraries if you need them. Click @samp{[Accept]}, and from
+@file{main.cpp}, again compile the whole project to force all
+dependent elements to compile:
+
+@example
+C-c . C
+@end example
+
+@section Step 8: Run your program
+
+You can run your program directly from @ede{}.
+
+@example
+C-c . R RET RET
+@end example
+
+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
@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
* Add/Remove target::
* Add/Remove files::
* Customize Features::
+* Project Local Variables::
* EDE Project Features::
@end menu
You can customize this behavior with the variable
@command{ede-auto-add-method}.
-@node Customize Features, EDE Project Features, Add/Remove files, Modifying your project
+@node Customize Features, Project Local Variables, Add/Remove files, Modifying your project
@section Customize Features
A project, and its targets, are objects using the @samp{EIEIO} object
(@code{ede-edit-file-target}). You should ``rescan'' the project
afterwards (@pxref{Miscellaneous commands}).
-@node EDE Project Features, , Customize Features, Modifying your project
+@node Project Local Variables, EDE Project Features, Customize Features, Modifying your project
+@section Project Local Variables
+
+EDE projects can store and manager project local variables. The
+variables are stored in the project, and will be restored when a
+project reloads.
+
+Projects which are not stored on disk WILL NOT restore your project
+local variables later.
+
+You can use @ref{Customize Features} to of the project to edit the
+project local variables. They are under the 'Settings' group as
+``Project Local Variables''.
+
+You can also use @kbd{M-x ede-set} to set a new variable local in the
+mini buffer.
+
+In multi-level projects such as Automake and Make generating projects,
+project local variables are installed from both the TOP most project,
+and the local directory's project. In that way, you can have some
+variables across your whole project, and some specific to a
+subdirectory.
+
+You can use project local variables to set any Emacs variable so that
+buffers belonging to different projects can have different settings.
+
+NOTE: When you use project-local variables with @ref{ede-cpp-root},
+the format is an association list. For example:
+
+@example
+(ede-cpp-root-project "SOMENAME"
+ :file "/dir/to/some/file"
+ :local-variables
+ '((grep-command . "grep -nHi -e ")
+ (compile-command . "make -f MyCustomMakefile all")))
+@end example
+
+The same is true when you use project-local variables with
+@ref{ede-java-root}. For example:
+
+@example
+(ede-java-root-project "SOMENAME"
+ :file "/dir/to/some/file"
+ :local-variables
+ '((grep-command . "grep -nHi -e ")
+ (compile-command . "ant")))
+@end example
+
+@node EDE Project Features, , Project Local Variables, Modifying your project
@section EDE Project Features
This section details user facing features of an @ede{} @samp{Make}
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, Simple projects, 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
To activate the speedbar in this mode, type @kbd{C-c . s}
(@code{ede-speedbar}).
-@node Simple projects, Extending EDE, Miscellaneous commands, top
-@section Simple Projects
+@menu
+* Make and Automake projects:: Project types of @samp{ede-project}
+* Automake direct projects:: Project interface on hand-written automake files.
+* Android projects:: Projects for Android development
+* Arduino projects:: Projects for Arduino sketches
+* Simple projects:: Projects @ede{} doesn't manage.
+@end menu
-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.
+@node Make and Automake projects
+@section Make and Automake projects
+
+A project of @samp{ede-project} type creates a file called
+@file{Project.ede} in every project directory. This is used to track
+your configuration information. If you configure this project to be
+in @samp{Makefile} mode, then this project will autogenerate a
+@file{Makefile}. If you configure it in @samp{Automake} mode a
+@file{Makefile.am} file will be created. The automake bootstrapping
+routines will also import and maintain a configure.am script and a
+host of other files required by Automake.
+
+@node Automake direct projects
+@section Automake direct projects
+
+The project type that reads @file{Makefile.am} directly is derived
+from the sources of the original @file{project-am.el} mode that was
+distributed independently. This mode eventually became @ede{}. The
+@samp{project-am} project will read existing automake files, but will
+not generate them automatically, or create new ones. As such, it is
+useful as a browsing tool, or as maintenance in managing file lists.
+
+@node Android projects
+@section Android projects
+
+An Android project of type @samp{ede-android-project} will detect and
+support development of Android apps. Android projects use an
+@file{AndroidManifest.xml} file. Always load your Manifest first in a
+running Emacs to make sure the project is identified correctly.
+
+Android projects can be created with @code{ede-new} but depend on a
+correctly configured Android SDK via @cedet{} support.
+
+@defun cedet-android-sdk-root
+@anchor{cedet-android-sdk-root}
+The root to the android @var{SDK}.
+@end defun
+
+Android projects support different configurations including compile,
+and install, which will upload a program to your Android device. It
+also supports several debugging tools via @file{android.el}.
+
+@node Arduino projects
+@section Arduino projects
+
+An arduino project of type @samp{ede-arduino-project} will read your
+@file{~/.arduino/preferences.txt} file, and identify your sketches.
+You will still need the Arduino IDE to set up your preferences and
+locate your arduino. After quitting the IDE, Emacs will be able to
+find your sketches, compile them, and upload them to your arduino.
+
+If you have the @file{arduino} command on your path, @ede{} will be
+able to find your SDK and compile your programs.
+
+@node Simple projects
+@section Simple Projects
-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-simple subclassing:: Create your own simple project.
-* ede-emacs:: A project for working with Emacs.
-* ede-linux:: A project for working with Linux kernels.
-* Custom Locate:: Customizing how to locate files in a simple project
+* 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
-@node ede-cpp-root
+@node ede-cpp-root, ede-java-root, Simple projects, Simple projects
@subsection ede-cpp-root
The @code{ede-cpp-root} project type allows you to create a single
The directory root for this cpp-root project.
@end table
+When creating a project with @code{ede-cpp-root}, you can get
+additional configurations via @ref{Project Local Variables}. Be aware
+that the format for project local variables is an association list.
+You cannot use @kbd{M-x ede-set} and have your project local variables
+persist between sessions.
If the cpp-root project style is right for you, but you want a dynamic
loader, instead of hard-coding path name values in your @file{.emacs}, you
@xref{ede-cpp-root-project}, for details about the class that defines
the @code{ede-cpp-root} project type.
-@node ede-simple subclassing
-@subsection ede-simple Subclassing
+@node ede-java-root, ede-emacs, ede-cpp-root, Simple projects
+@subsection ede-java-root
+
+Much like the project type @ref{ede-cpp-root}, the java variant is
+can be setup in your @file{.emacs} file and just marks a directory as
+the root of a java source tree.
+
+The @code{ede-java-root} project class knows a few things about Java
+projects. In particular, you can use it to control your classpath at
+both the system level, and for your project. If it is insufficient,
+you can subclass @code{ede-java-root-project} and add your own tweaks
+in just a few lines. See @ref{ede-cpp-root} for an example using the
+C++ variant.
+
+In the most basic case, add this to your @file{.emacs} file, modifying
+appropriate bits as needed.
+
+@example
+(ede-java-root-project "SOMENAME" :file "/dir/to/some/file" :srcroot '("src"))
+@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.
+
+Replace the value of :srcroot with a list of directories under the
+project root which contains Java sources. For example, if you have:
+
+@example
+~/myprojects/P1/
+~/myprojects/P1/src/
+~/myprojects/P1/src/com/ericsoft/MyCode.java
+~/myprojects/P1/doc/
+@end example
+
+Then @file{src} represents the directory under which all your Java
+code is. It is important that @file{src} is one step above the
+directory that is the base of your package name, such as
+@file{com/ericsoft} in the example above so that new files can be
+discovered via fully qualified name. You can have multiple such
+directories in one project, and each will be accessible.
+
+You can specify your classpath like this:
+
+@example
+(ede-java-root-project "NAME" :file "FILENAME"
+ :srcroot '("src")
+ :classpath '("/absolute/path.jar")
+ :localclasspath '( "/relative/path.jar" ))
+@end example
+
+In this example, @code{:classpath} specifies absolute paths somewhere
+on your system, and the explicit jar or source root directories
+@semantic{} will search when performing completions.
+
+The @code{:localclasspath} is like @code{:classpath}, but it will
+contain path names relative to the root of your project.
+
+If you want to override the file-finding tool with your own
+function you can do this:
+
+@example
+(ede-java-root-project "NAME" :file "FILENAME" :locate-fcn 'MYFCN)
+@end example
+
+Where @var{MYFCN} is a symbol for a function. The locate function can
+be used in place of @code{ede-expand-filename} so you can quickly
+customize your custom target to use specialized local routines instead
+of the default @ede{} routines. The function symbol must take two
+arguments:
-todo - Write some doc.
+@table @var
+@item NAME
+The name of the file to find.
+@item DIR
+The directory root for this java-root project.
+@end table
- In the meantime look in the commentary of ede-simple.el
+If you would like to create your Java projects dynamically, instead of
+putting them all in your @file{.emacs}, you can do that too. See
+@ref{ede-cpp-root} for details that can be applied to this project type.
-@node ede-emacs
+@node ede-emacs, ede-linux, ede-java-root, Simple projects
@subsection ede-emacs
The @code{ede-emacs} project automatically identifies an Emacs source
It pre-populates the C Preprocessor symbol map for correct parsing,
and has an optimized include file identification function.
-@node ede-linux
+@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
+@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
-is that the files in the project are not completely known to EDE.
+is that the files in the project are not completely known to EDE@.
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''.
@code{ede-locate-setup-options} with the names of different locate
objects. @ref{Miscellaneous commands}.
-Configure this in your @file{.emacs} before loading in CEDET or EDE.
+Configure this in your @file{.emacs} before loading in CEDET or EDE@.
If you want to add support for GNU Global, your configuration would
look like this:
@end example
That way, when a search needs to be done, it will first try using
-GLOBAL. If global is not available for that directory, then it will
+GLOBAL@. If global is not available for that directory, then it will
revert to the base locate object. The base object always fails to
find a file.
methods. See the code in @file{ede-locate.el} for GNU Global as a
simple example.
-@node Extending EDE, , Simple projects, 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
required.
@ede{} uses @eieio{}, the CLOS package for Emacs, to define two object
-superclasses, specifically the PROJECT and TARGET. All commands in
+superclasses, specifically the PROJECT and TARGET@. All commands in
@ede{} are usually meant to address the current project, or current
target.
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
examples.
@menu
+* Development Overview::
+* Detecting a Project::
* User interface methods:: Methods associated with keybindings
* Base project methods:: The most basic methods on @ede{} objects.
* Sourcecode objects:: Defining new sourcecode classes.
* Compilers:: Details of compiler classes.
@end menu
-@node User interface methods
+@node Development Overview, Detecting a Project, Extending EDE, Extending EDE
+@section Development Overview
+
+@ede{} is made up of a series of classes implemented with @eieio{}.
+These classes define an interface that can be used to create different
+types of projects.
+
+@ede{} defines two superclasses which are @code{ede-project} and
+@code{ede-target}. All commands in @ede{} are usually meant to
+address the current project, or current target.
+
+All specific projects in @ede{} derive subclasses of the @ede{} superclasses.
+In this way, specific behaviors such as how a project 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.
+
+Some example project types are:
+
+@table @code
+@item project-am
+Automake project which reads existing Automake files.
+@item ede-proj-project
+This project type will create @file{Makefiles},
+or @file{Makefile.am} files to compile your project.
+@item ede-linux
+This project type will detect linux source trees.
+@item ede-emacs
+This project will detect an Emacs source tree.
+@end table
+
+There are several other project types as well.
+
+The first class you need to know to create a new project type is
+@code{ede-project-autoload}. New instances of this class are needed
+to define how Emacs associates different files/buffers with different
+project types. All the autoloads are kept in the variable
+@code{ede-project-class-files}.
+
+The next most important class to know is @code{ede-project}. This is
+the baseclass defines how all projects behave. The basic pattern for
+a project is that there is one project per directory, and the topmost
+project or directory defines the project as a whole.
+
+Key features of @code{ede-project} are things like name and version
+number. It also holds a list of @code{ede-target} objects and a list
+of sub projects, or more @code{ede-project} objects.
+
+New project types must subclass @code{ede-project} to add special
+behavior. New project types also need to subclass @code{ede-target} to
+add specialty behavior.
+
+In this way, the common @ede{} interface is designed to work against
+@code{ede-project}, and thus all subclasses.
+
+@code{ede-project} subclasses @code{ede-project-placeholder}. This is
+the minimum necessary project needed to be cached between runs of
+Emacs. This way, Emacs can track all projects ever seen, without
+loading those projects into memory.
+
+Here is a high-level UML diagram for the @ede{} system created with @cogre{}..
+
+@example
++-----------------------+ +-----------------------+
+| | |ede-project-placeholder|
+|ede-project-class-files| +-----------------------+
+| | +-----------------------+
++-----------------------+ +-----------------------+
+ /\ ^
+ \/ /_\
+ | |
+ +--------------------+ +-----------+ +----------+
+ |ede-project-autoload| |ede-project| |ede-target|
+ +--------------------+<>--------------+-----------+<>-------+----------+
+ +--------------------+ +-----------+ +----------+
+ +--------------------+ +-----------+ +----------+
+ ^
+ /_\
+ |
+ +---------------------+-----------------+
+ | | |
+ | | |
+ | | |
+ +----------------+ +-------------------+ +---------+
+ |ede-proj-project| |project-am-makefile| |ede-emacs|
+ +----------------+ +-------------------+ +---------+
+ +----------------+ +-------------------+ +---------+
+ +----------------+ +-------------------+ +---------+
+@end example
+
+
+@node Detecting a Project, User interface methods, Development Overview, Extending EDE
+@section Detecting a Project
+
+Project detection happens with the list of @code{ede-project-autoload}
+instances stored in @code{ede-project-class-files}. The full project
+detection scheme works like this:
+
+@table @asis
+@item Step 1:
+@code{find-file-hook} calls @code{ede-turn-on-hook} on BUFFER.
+@item Step 2:
+@code{ede-turn-on-hook} turns on @code{ede-minor-mode}
+@item Step 3:
+@code{ede-minor-mode} looks to see if BUFFER is associated with any
+open projects. If not, it calls @code{ede-load-project-file} to find
+a project associated with the current directory BUFFER is in.
+@item Step 4:
+@code{ede-minor-mode} associates the found project with the current
+buffer with a series of variables, such as @code{ede-object}, and
+@code{ede-object-project} and @code{ede-object-root-project}.
+@end table
+
+Once a buffer is associated, @ede{} minor mode commands will operate
+on that buffer.
+
+The function @code{ede-load-project-file} is at the heart of detecting
+projects, and it works by looping over all the known project autoload
+types in @code{ede-project-autoload} using the utility
+@code{ede-directory-project-p}.
+
+The function @code{ede-directory-project-p} will call
+@code{ede-dir-to-projectfile} on every @code{ede-project-autoload}
+until one of them returns true. The method
+@code{ede-dir-to-projectfile} in turn gets the @code{:proj-file} slot
+from the autoload. If it is a string (i.e., a project file name), it
+checks to see if that exists in BUFFER's directory. If it is a
+function, then it calls that function and expects it to return a file
+name or nil. If the file exists, then this directory is assumed to be
+part of a project, and @code{ede-directory-project-p} returns the
+instance of @code{ede-project-autoload} that matched.
+
+If the current directory contains the file @code{.ede-ignore} then
+that directory is automatically assumed to contain no projects, even
+if there is a matching pattern. Use this type of file in a directory
+that may contain many other sub projects, but still has a Makefile of
+some sort.
+
+If the current directory is a project, then @ede{} scans upwards till
+it finds the top of the project. It does this by calling
+@code{ede-toplevel-project}. If this hasn't already been discovered,
+the directories as scanned upward one at a time until a directory with
+no project is found. The last found project becomes the project
+root. If the found instance of @code{ede-project-autoload} has a
+valid @code{proj-root} slot value, then that function is called instead
+of scanning the project by hand. Some project types have a short-cut
+for determining the root of a project, so this comes in handy.
+
+Getting back to @code{ede-load-project-file}, this now has an instance
+of @code{ede-project-autoload}. It uses the @code{load-type} slot to
+both autoload in the project type, and to create a new instance of the
+project type found for the root of the project. That project is added
+to the global list of all projects. All subprojects are then created
+and assembled into the project data structures.
+
+
+@node User interface methods, Base project methods, Detecting a Project, Extending EDE
@section User interface methods
These methods are core behaviors associated with user commands.
Rescan a project file, changing the data in the existing objects.
@end table
-@node Base project methods
+@node Base project methods, Sourcecode objects, User interface methods, Extending EDE
@section Base project methods
These methods are important for querying base information from project
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
List all documentation a project or target is responsible for.
@end table
-@node Sourcecode objects
+@node Sourcecode objects, Compiler and Linker objects, Base project methods, Extending EDE
@section Sourcecode objects
@ede{} projects track source file / target associates via source code
objects. The definitions for this is in @file{ede-source.el}. A source
code object contains methods that know how to identify a file as being
-of that class, (ie, a C file ends with @file{.c}). Some targets can
+of that class, (i.e., a C file ends with @file{.c}). Some targets can
handle many different types of sources which must all be compiled
together. For example, a mixed C and C++ program would have
instantiations of both sourcecode types.
@xref{Sourcecode}.
-@node Compiler and Linker objects
+@node Compiler and Linker objects, Project, Sourcecode objects, Extending EDE
@section Compiler and Linker objects
In order for a target to create a @file{Makefile}, it must know how to
Compiler instantiations must also insert variables specifying the
compiler it plans to use, in addition to creating Automake settings for
-@file{configure.in} when appropriate.
+@file{configure.ac} when appropriate.
Compiler objects are stored in the target objects as a list of
symbols, where the symbols value is the object. This enables the
@defindex sc
@defindex cm
-@node Project
+@node Project, Targets, Compiler and Linker objects, Extending EDE
@section Project
@menu
-* ede-project-placeholder ::
-* ede-project ::
-* ede-cpp-root-project ::
-* ede-simple-project ::
-* ede-simple-base-project ::
-* ede-proj-project ::
-* project-am-makefile ::
-* ede-step-project ::
+* ede-project-placeholder::
+* ede-project::
+* ede-cpp-root-project::
+* ede-simple-project::
+* ede-simple-base-project::
+* ede-proj-project::
+* project-am-makefile::
+* ede-step-project::
@end menu
-@node ede-project-placeholder
+@node ede-project-placeholder, ede-project, Project, Project
@subsection ede-project-placeholder
@pjindex ede-project-placeholder
Make sure placeholder @var{THIS} is replaced with the real thing, and pass through.
@end deffn
-@node ede-project
+@node ede-project, ede-cpp-root-project, ede-project-placeholder, Project
@subsection ede-project
@pjindex ede-project
@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.
+For remote locations use a path compatible with ange-ftp or EFS@.
You can also use TRAMP for use with rcp & scp.
@refill
Commit change to local variables in @var{PROJ}.
@end deffn
-@node ede-cpp-root-project
+@node ede-cpp-root-project, ede-simple-project, ede-project, Project
@subsection ede-cpp-root-project
@pjindex ede-cpp-root-project
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.
NAME - The name of the file to find.
DIR - The directory root for this cpp-root project.
-It should return the fully qualified file name passed in from NAME. If that file does not
+It should return the fully qualified file name passed in from NAME@. If that file does not
exist, it should return nil.
@refill
This knows details about or source tree.
@end deffn
-@node ede-simple-project
+@node ede-simple-project, ede-simple-base-project, ede-cpp-root-project, Project
@subsection ede-simple-project
@pjindex ede-simple-project
Commit any change to @var{PROJ} to its file.
@end deffn
-@node ede-simple-base-project
+@node ede-simple-base-project, ede-proj-project, ede-simple-project, Project
@subsection ede-simple-base-project
@pjindex ede-simple-base-project
@table @asis
@end table
-@node ede-proj-project
+@node ede-proj-project, project-am-makefile, ede-simple-base-project, Project
@subsection ede-proj-project
@pjindex ede-proj-project
@deffn Method ede-proj-setup-buildenvironment :AFTER this &optional force
Setup the build environment for project @var{THIS}.
-Handles the Makefile, or a Makefile.am configure.in combination.
+Handles the Makefile, or a Makefile.am configure.ac combination.
Optional argument @var{FORCE} will force items to be regenerated.
@end deffn
@end deffn
@deffn Method ede-proj-configure-synchronize :AFTER this
-Synchronize what we know about project @var{THIS} into configure.in.
+Synchronize what we know about project @var{THIS} into configure.ac.
@end deffn
@deffn Method ede-proj-makefile-insert-variables-new :AFTER this
@end deffn
@deffn Method ede-proj-configure-recreate :AFTER this
-Delete project @var{THIS}es configure script and start over.
+Delete project @var{THIS}'s configure script and start over.
@end deffn
@deffn Method ede-proj-makefile-insert-user-rules :AFTER this
@end deffn
@deffn Method ede-proj-configure-file :AFTER this
-The configure.in script used by project @var{THIS}.
+The configure.ac script used by project @var{THIS}.
@end deffn
@deffn Method ede-commit-project :AFTER proj
Commit change to local variables in @var{PROJ}.
@end deffn
-@node project-am-makefile
+@node project-am-makefile, ede-step-project, ede-proj-project, Project
@subsection project-am-makefile
@pjindex project-am-makefile
buffer being in order to provide a smart default target type.
@end deffn
-@node ede-step-project
+@node ede-step-project, , project-am-makefile, Project
@subsection ede-step-project
@pjindex ede-step-project
@deffn Method ede-proj-setup-buildenvironment :AFTER this &optional force
Setup the build environment for project @var{THIS}.
-Handles the Makefile, or a Makefile.am configure.in combination.
+Handles the Makefile, or a Makefile.am configure.ac combination.
Optional argument @var{FORCE} will force items to be regenerated.
@end deffn
Commit change to local variables in @var{PROJ}.
@end deffn
-@node Targets
+@node Targets, Sourcecode, Project, Extending EDE
@section Targets
@menu
-* ede-target ::
-* ede-proj-target ::
-* ede-proj-target-makefile ::
-* semantic-ede-proj-target-grammar ::
-* ede-proj-target-makefile-objectcode ::
-* ede-proj-target-makefile-archive ::
-* ede-proj-target-makefile-program ::
-* ede-proj-target-makefile-shared-object ::
-* ede-proj-target-elisp ::
-* ede-proj-target-elisp-autoloads ::
-* ede-proj-target-makefile-miscelaneous ::
-* ede-proj-target-makefile-info ::
-* ede-proj-target-scheme ::
-* project-am-target ::
-* project-am-objectcode ::
-* project-am-program ::
-* project-am-header-noinst ::
-* project-am-header-inst ::
-* project-am-lisp ::
-* project-am-texinfo ::
-* project-am-man ::
+* ede-target::
+* ede-proj-target::
+* ede-proj-target-makefile::
+* semantic-ede-proj-target-grammar::
+* ede-proj-target-makefile-objectcode::
+* ede-proj-target-makefile-archive::
+* ede-proj-target-makefile-program::
+* ede-proj-target-makefile-shared-object::
+* ede-proj-target-elisp::
+* ede-proj-target-elisp-autoloads::
+* ede-proj-target-makefile-miscelaneous::
+* ede-proj-target-makefile-info::
+* ede-proj-target-scheme::
+* project-am-target::
+* project-am-objectcode::
+* project-am-program::
+* project-am-header-noinst::
+* project-am-header-inst::
+* project-am-lisp::
+* project-am-texinfo::
+* project-am-man::
@end menu
-@node ede-target
+@node ede-target, ede-proj-target, Targets, Targets
@subsection ede-target
@tgindex ede-target
@end deffn
@deffn Method ede-buffer-header-file :AFTER this buffer
-There are no default header files in EDE.
+There are no default header files in EDE@.
Do a quick check to see if there is a Header tag in this buffer.
@end deffn
Retrieves the slot @code{menu} from an object of class @code{ede-target}
@end deffn
-@node ede-proj-target
+@node ede-proj-target, ede-proj-target-makefile, ede-target, Targets
@subsection ede-proj-target
@tgindex ede-proj-target
@end deffn
-@node ede-proj-target-makefile
+@node ede-proj-target-makefile, semantic-ede-proj-target-grammar, ede-proj-target, Targets
@subsection ede-proj-target-makefile
@tgindex ede-proj-target-makefile
Use @var{CONFIGURATION} as the current configuration to query.
@end deffn
-@node semantic-ede-proj-target-grammar
+@node semantic-ede-proj-target-grammar, ede-proj-target-makefile-objectcode, ede-proj-target-makefile, Targets
@subsection semantic-ede-proj-target-grammar
@tgindex semantic-ede-proj-target-grammar
@end deffn
-@node ede-proj-target-makefile-objectcode
+@node ede-proj-target-makefile-objectcode, ede-proj-target-makefile-archive, semantic-ede-proj-target-grammar, Targets
@subsection ede-proj-target-makefile-objectcode
@tgindex ede-proj-target-makefile-objectcode
@end deffn
-@node ede-proj-target-makefile-archive
+@node ede-proj-target-makefile-archive, ede-proj-target-makefile-program, ede-proj-target-makefile-objectcode, Targets
@subsection ede-proj-target-makefile-archive
@tgindex ede-proj-target-makefile-archive
@deffn Method ede-proj-makefile-insert-source-variables :PRIMARY this
Insert bin_PROGRAMS variables needed by target @var{THIS}.
-We aren't acutally inserting SOURCE details, but this is used by the
+We aren't actually inserting SOURCE details, but this is used by the
Makefile.am generator, so use it to add this important bin program.
@end deffn
-@node ede-proj-target-makefile-program
+@node ede-proj-target-makefile-program, ede-proj-target-makefile-shared-object, ede-proj-target-makefile-archive, Targets
@subsection ede-proj-target-makefile-program
@tgindex ede-proj-target-makefile-program
@end deffn
-@node ede-proj-target-makefile-shared-object
+@node ede-proj-target-makefile-shared-object, ede-proj-target-elisp, ede-proj-target-makefile-program, Targets
@subsection ede-proj-target-makefile-shared-object
@tgindex ede-proj-target-makefile-shared-object
@deffn Method ede-proj-makefile-insert-automake-pre-variables :AFTER this
Insert bin_PROGRAMS variables needed by target @var{THIS}.
-We aren't acutally inserting SOURCE details, but this is used by the
+We aren't actually inserting SOURCE details, but this is used by the
Makefile.am generator, so use it to add this important bin program.
@end deffn
-@node ede-proj-target-elisp
+@node ede-proj-target-elisp, ede-proj-target-elisp-autoloads, ede-proj-target-makefile-shared-object, Targets
@subsection ede-proj-target-elisp
@tgindex ede-proj-target-elisp
is found, such as a @code{-version} variable, or the standard header.
@end deffn
-@node ede-proj-target-elisp-autoloads
+@node ede-proj-target-elisp-autoloads, ede-proj-target-makefile-miscelaneous, ede-proj-target-elisp, Targets
@subsection ede-proj-target-elisp-autoloads
@tgindex ede-proj-target-elisp-autoloads
@end deffn
-@node ede-proj-target-makefile-miscelaneous
+@node ede-proj-target-makefile-miscelaneous, ede-proj-target-makefile-info, ede-proj-target-elisp-autoloads, Targets
@subsection ede-proj-target-makefile-miscelaneous
@tgindex ede-proj-target-makefile-miscelaneous
@end deffn
-@node ede-proj-target-makefile-info
+@node ede-proj-target-makefile-info, ede-proj-target-scheme, ede-proj-target-makefile-miscelaneous, Targets
@subsection ede-proj-target-makefile-info
@tgindex ede-proj-target-makefile-info
when working in Automake mode.
@end deffn
-@node ede-proj-target-scheme
+@node ede-proj-target-scheme, project-am-target, ede-proj-target-makefile-info, Targets
@subsection ede-proj-target-scheme
@tgindex ede-proj-target-scheme
@end deffn
-@node project-am-target
+@node project-am-target, project-am-objectcode, ede-proj-target-scheme, Targets
@subsection project-am-target
@tgindex project-am-target
Edit the target associated w/ this file.
@end deffn
-@node project-am-objectcode
+@node project-am-objectcode, project-am-program, project-am-target, Targets
@subsection project-am-objectcode
@tgindex project-am-objectcode
There are no default header files.
@end deffn
-@node project-am-program
+@node project-am-program, project-am-header-noinst, project-am-objectcode, Targets
@subsection project-am-program
@tgindex project-am-program
@end table
@end table
-@node project-am-header-noinst
+@node project-am-header-noinst, project-am-header-inst, project-am-program, Targets
@subsection project-am-header-noinst
@tgindex project-am-header-noinst
Return the default macro to 'edit' for this object.
@end deffn
-@node project-am-header-inst
+@node project-am-header-inst, project-am-lisp, project-am-header-noinst, Targets
@subsection project-am-header-inst
@tgindex project-am-header-inst
Return the default macro to 'edit' for this object.
@end deffn
-@node project-am-lisp
+@node project-am-lisp, project-am-texinfo, project-am-header-inst, Targets
@subsection project-am-lisp
@tgindex project-am-lisp
Return the default macro to 'edit' for this object.
@end deffn
-@node project-am-texinfo
+@node project-am-texinfo, project-am-man, project-am-lisp, Targets
@subsection project-am-texinfo
@tgindex project-am-texinfo
@end deffn
@deffn Method project-compile-target-command :AFTER this
-Default target t- use when compiling a texinfo file.
+Default target to use when compiling a texinfo file.
@end deffn
@deffn Method ede-documentation :AFTER this
files in the project.
@end deffn
-@node project-am-man
+@node project-am-man, , project-am-texinfo, Targets
@comment node-name, next, previous, up
@subsection project-am-man
@tgindex project-am-man
Return the default macro to 'edit' for this object type.
@end deffn
-@node Sourcecode
+@node Sourcecode, Compilers, Targets, Extending EDE
@section Sourcecode
The source code type is an object designed to associated files with
targets.
@menu
-* ede-sourcecode ::
+* ede-sourcecode::
@end menu
-@node ede-sourcecode
+@node ede-sourcecode, , Sourcecode, Sourcecode
@subsection ede-sourcecode
@scindex ede-sourcecode
Return non-@code{nil} if @var{THIS} will take @var{FILENAME} as an auxiliary .
@end deffn
-@node Compilers
+@node Compilers, , Sourcecode, Extending EDE
@section Compilers
The compiler object is designed to associate source code with
compile commands.
@menu
-* ede-compilation-program ::
-* ede-compiler ::
-* ede-object-compiler ::
-* ede-linker ::
+* ede-compilation-program::
+* ede-compiler::
+* ede-object-compiler::
+* ede-linker::
@end menu
-@node ede-compilation-program
+@node ede-compilation-program, ede-compiler, Compilers, Compilers
@subsection ede-compilation-program
@cmindex ede-compilation-program
@end deffn
-@node ede-compiler
+@node ede-compiler, ede-object-compiler, ede-compilation-program, Compilers
@subsection ede-compiler
@cmindex ede-compiler
@end deffn
-@node ede-object-compiler
+@node ede-object-compiler, ede-linker, ede-compiler, Compilers
@subsection ede-object-compiler
@cmindex ede-object-compiler
Insert variables needed by the compiler @var{THIS}.
@end deffn
-@node ede-linker
+@node ede-linker, , ede-object-compiler, Compilers
@subsection ede-linker
@cmindex ede-linker
@end table
@end table
+@node GNU Free Documentation License, , Extending EDE, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
@bye