CEDET Git

787 lines (603 with data), 26.6 kB

\input texinfo
@setfilename ede.info
@settitle Emacs Development Environment

@copying
This file describes EDE, the Emacs Development Environment.

Copyright @copyright{} 1998-2001, 2004-2005, 2008-2013, 2015  Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below.  A copy of the license
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.''
@end quotation
@end copying

@dircategory Emacs misc features
@direntry
* EDE: (ede).                   The Emacs Development Environment.
@end direntry

@titlepage
@center @titlefont{EDE (The Emacs Development Environment)}
@sp 4
@center by Eric Ludlam
@end titlepage
@page

@macro cedet{}
@i{CEDET}
@end macro

@macro semantic{}
@i{Semantic}
@end macro

@macro srecode{}
@i{SRecode}
@end macro

@macro eieio{}
@i{EIEIO}
@end macro

@macro ede{}
@i{EDE}
@end macro

@macro cogre{}
@i{COGRE}
@end macro

@macro speedbar{}
@i{Speedbar}
@end macro

@contents

@node Top
@top EDE
@comment  node-name,  next,  previous,  up

@ede{} is the Emacs Development Environment: an Emacs extension that
simplifies integrating project management workflows in Emacs.  It has
features typical of other IDEs such as compiling and running programs.

Using an @ede{} project is as simple as enabling
@code{(global-ede-mode 1)} and letting @ede{} identify the files
associated with your build environment.  If you are just starting out,
@ede{} can manage or create your makefiles and other build environment
files, allowing you to concentrate on writing code rather than support
files.

@ede{} is also a place to configure your projects so other tools in
Emacs know more about your code, and can help you.  For example, the
@semantic{} parser and smart completion engines use @ede{} project
metadata to help parse your files and speed up file searches.

@ifnottex
@insertcopying
@end ifnottex

@menu
* Introduction::

* Quick Start - wrapper::       Wrap existing project with @ede{}
* Wrapper Projects::            Details about specific wrapper projects
* Root Projects::               Details about setting up @b{root} projects
* Generic Projects::            Details about using @b{generic} projects
* Compilation Database projects:: Projects configured via a compilation database

* Quick Start - from scratch::  Start a project from scratch
* Managed Projects::            Using a managed project built from scratch

* EDE Mode::                    Turning on @ede{} mode.
* Miscellaneous commands::      Other project related commands.
* Extending EDE::               Programming and extending @ede{}.
* GNU Free Documentation License::  The license for this documentation.
@end menu

@node Introduction
@chapter Introduction

@ede{} is a generic interface for managing projects.  For a user, it
specifies a single set of menus and keybindings, while supporting
pre-existing projects using a range of different tools.  For
developers, it provides an interface to gain meta-data about a user
project to improve a tools usefulness.

@ede{} can be used to either:
@itemize
@item Wrap an existing project
@item Create and manage a project
@end itemize

All projects types in EDE support a few basic concepts about the
@b{project} or its @b{targets}, although some project types do not
support modifying @b{target}s or all @b{project} options.

@section What is a project?

In @ede{}, a project consists of a directory hierarchy, a set of meta
data, command features, and a set of targets. Not all projects support
all types of meta data or commands.

The meta-data includes the project's version number, and might include
additional features, such as C/C++ Include and System Include paths,
or Java's classpath.

A project also has commands available, including a concept of @b{compile},
@b{debug}, and @b{run}.

The Project menu includes @code{Add target} and @code{Remove target}
and a way to select a configuration, though not all project types
support this.

@section What is a target?

In @ede{}, targets are a way to subdivide your project into different
units, usually grouped by purpose, or grouped by language type.
Internally, all projects have targets, but some projects do not have
any useful features associated with their targets.

For projects supporting targets, the different targets have additional
metadata, such as which subset of files belong to a given target, and
supports commands, such as how to compile or debug that target.

The Development menu includes a Target entry which has @code{Add file}
and @code{Remove file}, though not all projects support this.

@node Quick Start - wrapper
@chapter Quick Start - Wrapping an existing project

If you already have a project, all you need to do is enable
@ede{} in your @code{.emacs} file like this:

@example
(global-ede-mode 1)
@end example

If there is a project type for your code, @ede{} will automatically
detect it.  Some example @ref{Wrapper Projects} include:

@itemize
@item Automake
@item Linux kernel
@item Emacs source
@item Android SDK projects
@item Arduino sketches
@item Java projects including ant, maven, lein
@item compdb & Ninja enabled projects
@end itemize

There are also two kinds of @ref{Root Projects}.

@itemize
@item C++
@item Java
@end itemize

There are also a wide range of very simple @ref{Generic Projects}, such
as:

@itemize
@item Projects identified by Version Control
@item Makefile
@item CMake
@item SCons
@end itemize

If your project type isn't supported yet, you can add support with
either the @ref{Root Projects} for those supported langauges, or with
the @ref{Generic Projects}.

@node Wrapper Projects
@chapter Wrapper Projects

Wrapper projects can identify projects that have alreayd been setup by
identifying key files.  If you work with these types of projects, you
will be all set after you enable @ede{} with no extra configuration
needed.

@menu
* Automake::                    Project for hand-written Automake.
* Emacs::                       Project for working with Emacs.
* Linux::                       Project for working with Linux kernels.
* Java::                        Projects for different generic Java builds
* Android projects::            Projects for Android development
* Arduino projects::            Projects for Arduino sketches
@end menu

@node Automake
@section Hand Written Automake

The Automake project identifies projects where the Automake files
have been hand written.  This project reads your Automake files, and
can identify your targets and can build your project.

Each source file can be identified with one or more targets, and you
can use the @code{ede-compile-target} command, or build the whole
project.

This project type can also keep your Automake files updated by adding
new source files to different targets for you.

If you edit your Automake files by hand, be sure to use
@code{ede-rescan-toplevel} to keep @ede{} up to date.

@node Emacs
@section Emacs

The Emacs project automatically identifies an Emacs source
tree, and enables an @ede{} project mode for it.

It pre-populates the C Preprocessor symbol map for correct parsing,
and has an optimized include file identification function.

@node Linux
@section Linux Kernel

The @code{ede-linux} project will automatically identify a Linux
Kernel source tree, and enable and @ede{} project mode for it.

The Linux project enables the project and target compile menus.  It
pre-populates the C Preprocessor symbol map for reasonable parsing,
and has an optimized include file identification function.  It also
supports @semantic{} code parsing with customized platform defines
set.

@node Java
@section Java projects

There are several Java projects for detecting some common Java build
environments and setting them up for @semantic{} parsing and
compilation.  Supported projects are:

@itemize
@item Ant
@item Maven
@item Lein
@end itemize

@@TODO Write some more.

@node Android projects
@section Android projects

An Android project will detect and support development of Android
apps.  Android projects use an @file{AndroidManifest.xml} file.

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 debug,
release, and instrument.  It supports compile, debug, and upload,
which will upload a program to your Android device.  It also supports
several debugging tools via @file{android.el}.

This project also supports @semantic{} by enabling smart completion of
system symbols derived from the @file{android.jar} file found in the
SDK.

@node Arduino projects
@section Arduino projects

An arduino project will read your preferences.  On Linux it will
automatically find @file{~/.arduino/preferences.txt} file, and
identify your sketches.  On windows, you will need to tell Emacs where
your preferences are, perhaps like this:

@example
(setq ede-arduino-preferences-file
    (expand-file-name (substitute-in-file-name "$APPDATA/Arduino15/preferences.txt")))
@end example

You will still need the Arduino IDE to set up your preferences and
locate your arduino.  After using 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.

Arduino projects support compiling and uploading sketches to your Arduino.

@node Root Projects
@chapter Root Projects

Root projects are a way to configure Emacs to identify and customize a
project that doesn't have an existing wrapper project, and without
leaving special @ede{} project files behind.

Instead, you configure these projects in your @file{.emacs} file with
just enough information to support @semantic{}, or whichever tool you
are need @ede{} to support.

@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.
@end menu


@node ede-cpp-root
@section ede-cpp-root

The @code{ede-cpp-root} project type allows you to configure a project
in your @file{.emacs} file.  It allows @ede{} to provide the
@semantic{} package with the ability to find header files quickly.

The @code{ede-cpp-root} class knows a few things about C++ projects,
such as the prevalence of "include" directories, and typical
file-layout stuff.  If this isn't sufficient, you can subclass
@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 "NAME" :file "/dir/to/some/file")
@end example

Replace @var{NAME} 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:

@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
name is expanded.

The include path only affects C/C++ header files.  Use the slot
@code{:header-match-regexp} to change it.

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)
@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:

@table @var
@item NAME
The name of the file to find.
@item DIR
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
can do that too, but you will need to write some lisp code.

To do that, you need to add an entry to the
@code{ede-project-class-files} list, and also provide two functions to
teach @ede{} how to load your project pattern

It would look like this:

@example
(defun MY-FILE-FOR-DIR (&optional dir)
  "Return a full file name to the project file stored in DIR."
  <write your code here, or return nil>
  )

(defun MY-ROOT-FCN ()
  "Return the root fcn for `default-directory'"
  ;; You might be able to use `ede-cpp-root-project-root'
  ;; and not write this at all.
  )

(defun MY-LOAD (dir)
  "Load a project of type `cpp-root' for the directory DIR.
Return nil if there isn't one."
  ;; Use your preferred construction method here.
  (ede-cpp-root-project "NAME" :file (expand-file-name "FILE" dir)
                               :locate-fcn 'MYFCN)
  )

(add-to-list 'ede-project-class-files
             (ede-project-autoload "cpp-root"
              :name "CPP ROOT"
              :file 'ede-cpp-root
              :proj-file 'MY-FILE-FOR-DIR
              :proj-root 'MY-ROOT-FCN
              :load-type 'MY-LOAD
              :class-sym 'ede-cpp-root)
             t)
@end example

This example only creates an auto-loader, and does not create a new kind
of project.

See @code{ede-cpp-root-project}, for details about the class that defines
the @code{ede-cpp-root} project type.

@node ede-java-root
@section 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:

@table @var
@item NAME
The name of the file to find.
@item DIR
The directory root for this java-root project.
@end table

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 Generic Projects
@chapter Generic Projects

Generic projects makes it easy to configure different kinds of build
systems as an EDE project when a specialized project type is not
available.

Generic projects are disabled by default because they have the
potential to interfere with other projects.  To use the generic
project sytem to start detecting projects, you need to enable it.

@example
(ede-enable-generic-projects)
@end example

@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

@menu
* Customizing a Generic Project::
* Creating new Generic Projects::
@end menu

@node Customizing a Generic Project
@section Customizing a Generic Project

To customize a project identified with @ede{}'s generic project
system, use the command

@example
M-x customize-project RET
@end example

Generic projects support a special configuration which is saved when
you finish customizing it.  The next time you open your project, your
customizations will be restored.  The configurations are saved at the
root of the identified project.

Generic projects support configuration of:
@itemize
@item Project compile command
@item Project debug command
@item Run project command
@item C configuration, such as include paths, system includes, and
custom macros.
@item Java configuration, such as classpath.
@end itemize

Because generic project config files are Emacs Lisp code, loading them
is considered unsafe.  You will be asked before a configuration file
is loaded into Emacs, or to add a given directory to your 'safe' list.

@node Creating new Generic Projects
@section Creating new Generic Projects

Adding support for a new generic project requires 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}.

To add a new autoloader, use the below command.  See the next two
sections for examples.

@defun ede-generic-new-autoloader internal-name external-name projectfile class
@anchor{ede-generic-new-autoloader}
Add a new @ede{} Autoload instance for identifying a generic project.
@var{INTERNAL-NAME} is a long name that identifies this project type.
@var{EXTERNAL-NAME} is a shorter human readable name to describe the project.
@var{PROJECTFILE} is a file name that identifies a project of this type to @ede{}, such as
a @file{Makefile}, or @file{SConstruct} file.
@var{CLASS} is the @eieio{}  It should subclass
the class @dfn{ede-generic-project} project.
@end defun

@subsection Add Generic Support for a Version Control system
If you want to create a generic project loader for your favorite
Version Control system, you just need to add a new autoloader for it.
Here are two examples from @file{ede/generic.el}:

@example
  (ede-generic-new-autoloader "generic-git" "Generic Git"
			      ".git" 'ede-generic-vc-project)
  (ede-generic-new-autoloader "generic-bzr" "Generic Bazaar"
			      ".bzr" 'ede-generic-vc-project)
@end example

@subsection Add Generic Support for a build system
If you want to create a generic project loader for your favorite build
system, 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.

@c COMPDB inclusion
@include ede-compdb.texi

@c Managed project inclusion
@include ede-manage.texi

@node EDE Mode
@chapter @ede{} Mode

@ede{} is implemented as a minor mode that adds project support to any
buffer.  You can enable @ede{} for all buffers by running the command
@code{global-ede-mode}, or by putting this in your init file:

@example
(global-ede-mode t)
@end example

Activating @ede{} adds a menu named @samp{Development} to the menu
bar.  This menu provides several menu items for high-level @ede{}
commands.  These menu items, and their corresponding keybindings, are
independent of the type of project you are actually working on.


@node Miscellaneous commands
@chapter Miscellaneous commands

@@TODO - this section needs to be updated.

If you opt to go in and edit @ede{} project files directly---for
instance, by using @kbd{C-c . e} (@pxref{Customize Features})---you
must then ``rescan'' the project files to update the internal data
structures.  To rescan the current project, type @kbd{C-c . g}
(@code{ede-rescan-toplevel}).

@ede{} can help you find files in your project, via the command
@kbd{C-c . f} (@code{ede-find-file}).  This prompts for a file name;
you need not specify the directory.  EDE then tries to visit a file
with that name somewhere in your project.

@ede{} can use external tools to help with file finding.  To do this,
customize @code{ede-locate-setup-options}.

@defvar ede-locate-setup-options
@anchor{ede-locate-setup-options}
List of locate objects to try out by default.
Listed in order of preference.  If the first item cannot be used in
a particular project, then the next one is tried.
It is always assumed that @dfn{ede-locate-base} is at end of the list.
@end defvar

@ede{} also provides a project display mode for the speedbar
(@pxref{Speedbar,,,emacs,GNU Emacs Manual}).  This allows you to view
your source files as they are structured in your project: as a
hierarchical tree, grouped according to target.

To activate the speedbar in this mode, type @kbd{C-c . s}
(@code{ede-speedbar}).

@menu
* Custom Locate::             Projects @ede{} doesn't manage.
@end menu


@node Custom Locate
@section 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@.
When the EDE API is used to try and file files by some reference name
in the project, then that could fail.

@ede{} can therefore use some external locate commands, such as the unix
``locate'' command, or ``GNU Global''.

Configuration of the tool you want to use such as @code{locate}, or
@code{global} will need to be done without the aid of @ede{}.  Once
configured, however, @ede{} can use it.

To enable one of these tools, set the variable
@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@.
If you want to add support for GNU Global, your configuration would
look like this:

@example
(setq ede-locate-setup-options '(ede-locate-global ede-locate-base))
@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
revert to the base locate object.  The base object always fails to
find a file.

You can add your own locate tool but subclassing from
@code{ede-locate-base}.  The subclass should also implement two
methods.  See the code in @file{ede-locate.el} for GNU Global as a
simple example.

@@TODO - Add ID Utils and CScope examples

More on idutils and cscope is in the CEDET manual, and they each have
their own section.

@c EXTEND include
@include ede-extend.texi

@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi

@bye