\input texinfo   @c -*-texinfo-*-
@c
@c $Id: ede.texi,v 1.10 2001/04/27 00:23:10 zappo Exp $
@c
@setfilename ede.info
@settitle Emacs Development Environment

@ifinfo
@format
START-INFO-DIR-ENTRY
* ede: (ede).       Objects for Emacs
END-INFO-DIR-ENTRY
@end format
@end ifinfo

@titlepage
@sp 10
@center @titlefont{ede}
@vskip 0pt plus 1 fill
Copyright @copyright{} 1998, 1999, 2000, 2001 Eric M. Ludlam
@end titlepage

@node Top, , , (dir)Top
@comment  node-name,  next,  previous,  up

EDE is a collection of definitions called the 
@emph{Emacs Development Extensions}.  EDE provides the gloss that
simplifies the learning curve for all the very useful functionality of
building and debugging under emacs.  In doing so it attempts to emulate
a typical IDE (Integrated Development Environment).  What this means is
that EDE will manage or create your makefiles and other building
environment duties so the developer can concentrate on code, and not
support files.  In doing so, it will be much easier for new programmers
to learn and adopt the GNU ways of doing things.
@refill

@menu
* EDE Mode::                Turning on EDE mode.
* 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.
* Project types::           There are different types of projects.
* Extending EDE::           Programming tips when extending.
@end menu

@node EDE Mode, Creating a project, Top, Top
@chapter EDE Mode

EDE is implemented as a minor-mode, which augments other modes such as C
mode, and Texinfo mode.  You can turn EDE on for all buffers by running
the command @code{global-ede-mode}, or by putting this in your
@file{~/.emacs} file.

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

When EDE is active for a given buffer, the menu item ``Project''
appears.  This menu contains several high-level functions to make
working on a code set easier.  These items and keybindings never change
regardless of the type of project you are actually working on.

The @file{ede.el} file is a minimal set of loading routines.  When
different types of projects are encountered, source code for those
projects are loaded at that time.

@node Creating a project, Modifying your project, EDE Mode, Top
@chapter Creating a project

EDE can support many different types of projects.  When creating a new
project with the command `ede-new' (or "Create Project" in the
menu) you must choose the type of project you would like to create.
@xref{Project types}.

Each type has it's own benefits or language specific enhancements.  You
will be prompted for the type of project you would like to create.  The
simplest and most language agnostic project type is @samp{Make}.  A
derivation of this is the @samp{Automake} type.

Not all project types can be created in this way.  For example, there
are two ways to handle Automake based projects.  One is through the
@code{ede-project} class, and the other through @code{project-am}
class.  @code{project-am} will autoload in any GNU Automake based
distribution that does not contain a @file{Project.ede} file.

@section Creating a subproject

A subproject is merely a project in a subdirectory in some other
projects control.  You can create a subproject by using the
@command{ede-new} command (or @samp{"Create Project"} from the menu)
while a in a subdirectory below an existing project.  This new project
will be automatically added to the parent project, and will be
automatically loaded when the parent is read.

When using a project command that invovles a makefile, EDE uses
the top-most project's makefile as a starting place for the build.  How
the toplevel project handles subprojects in the build process is
dependendent on that project's type.

@node Modifying your project, Building and Debugging, Creating a project, Top
@chapter Modifying your project

A project, and it's targets, are objects using the @samp{EIEIO} object
system. @xref{(eieio)EIEIO}.  These objects have data fields containing
important information related to your work.  Of note is that a project
has a list of subprojects (sub directories), and targets (things to
build from sources).  Targets in turn have lists of source code, and
information on how to convert that source code into compiled programs or
documentation.

A project conceptually mirrors a Makefile build tree.  You can create a
new target with the @command{ede-new-target} command @kbd{C-c . t}.  Once
created, you can now put source files into this target.  You can remove
a target with the command @code{ede-delete-target}.

You can add and remove files into targets with the command
@command{ede-add-file} and @command{ede-remove-file} bound to @kbd{C-c . a}
and @kbd{C-c . d} respectively.  These commands will add the current
buffer's file into the target.

When working in an existing project's directory, and a new file is read
into Emacs, EDE will attempt to auto-add that file to a target of your
choice.  You can customize the behavior with the variable 
@command{ede-auto-add-method}.

If these high-level functions aren't enough, you can tweak all
user-customizable fields at any time by running the command
@command{customize-project} or @command{customize-target}.  This will load the
given object into an immediate-mode customization buffer where you tweak
individual slots.  This is usually necessary for project modes that are
very complex.

Some project modes do not have a project file, but directly read a
Makefile, or existing file.  Instead of letting you directly edit the
object, you can edit the file.  Use the command
@command{ede-edit-file-target} bound to @kbd{C-c . e}.

@node Building and Debugging, Miscellaneous commands, Modifying your project, Top
@chapter Building and Debugging

EDE assumes you are writing some sort of program, so attempts to
facilitate this activity.  EDE will associate the current buffer with a
target.  The target then knows how to compile or debug the given source
file.

The following commands enable compilation and debugging.

@table @kbd
@item C-c . c
Compile the current target.
@item C-c . C
Compile the entire project.
@item c-c . D
Debug the current target.
@item ede-make-dist
Build a distribution file for your project.
@end table

@node Miscellaneous commands, Project types, Building and Debugging, Top
@chapter Miscellaneous commands

EDE also supports the speedbar package.  While speedbar works great
against directories already, EDE provides a project display mode.  This
lets you look at your source files as they are structured in your
project.  Thus, where many files may be clumped together in one
directory, the Project view will provide a hierarchical view of your
files as grouped by target.

You can activate speedbar in this mode with the command @command{ede-speedbar}.

@node Project types, Extending EDE, Miscellaneous commands, Top
@chapter Project types

There are two types of project modes currently.  One is
@samp{ede-project}, and shows up as @samp{Make} and @samp{Automake} when
creating new projects.  @samp{ede-project} lives in the file
@file{ede-proj}.  The other is project type lives in
@file{project-am.el}, and handles automake projects directly from the
Makefiles.  EDE cannot make new projects of this type, assuming the user
will do it themselves.  Use @samp{ede-project} in @samp{Automake} mode
to have EDE create @file{Makefile.am} file, and a @file{configure.in}
file.
@refill

@samp{ede-project} creates a file called @file{Project.ede} in a given
project directory.  This is used to track your configureation
information.  When compiling, this project will autogenerate a
@file{Makefile}, or a @file{Makefile.am} file.

The project type that reads @file{Makefile.am} directly is derived from
the sources of the original @file{project-am.el} mode I wrote.  This
mode eventually became EDE.  The automake 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 Extending EDE, ,Project types, Top
@chapter Extending EDE

EDE makes use of EIEIO, the CLOS package for Emacs.  This lets EDE
define two object superclasses, specifically the PROJECT and 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.  For details on different types of projects,
@xref{Project types}.  @xref{(eieio)Top}. For details on using EIEIO to
extending classes, and writing methods.

It is most likely that a new target type is needed in one of the
existing project types.  The rest of this chapter will discuss extending
the @code{ede-project} class, and it's targets.  See
@file{project-am.el} for basic details on adding targets to it.

For the @code{ede-project} type, the core target class is called
@code{ede-proj-target}.  Inheriting from this will give you everything
you need to start, including adding your sources into the makefile.  If
you also need additional rules in the makefile, you will want to inherit
from @code{ede-proj-target-makefile}.  You may want to also add new
fields to track important information.

Once your new class exists, you will want to fill in some basic methods.
See the @file{ede-skel.el} file for examples of these.  The files
@file{ede-proj-info.el} and @file{ede-proj-elisp} are two interesting
examples.

@section User interface methods

These methods are core behaviors associated with user commands.

@table @code
@item project-add-file
Add a file to your project.  Override this if you want to put new
sources into different fields depending on extension, or other details.
@item project-remove-file
Reverse of project-add-file.
@item project-compile-target
Override this if you want to do something special when the user
"compiles" this target.  The default is probably fine.
@item project-debug-target
What to do when a user wants to debug your target.
@item project-update-version
Easily updated the version number of your project.
@item project-edit-file-target
Edit the file the project's information is stored in.
@item project-new-target
Create a new target in a project.
@item project-delete-target
Delete a target from a project.
@item project-make-dist
Make a distribution (tar archive) of the project.
@item project-rescan
Rescan a project file, changing the data in the existing objects.
@end table

@section Base project methods

These methods are important for querying base information from project
and target types:

@table @code
@item ede-name
Return a string that is the name of this target.
@item ede-target-name
Return a string that is the name of the target used by a Make system.
@item ede-description
A brief description of the project or target.  This is currently used
by the @samp{ede-speedbar} interface.
@item ede-want-file-p
Return non-nil if a target will accept a given file.
It is generally unecessary to override this.  See the section on source
code.
@item ede-buffer-mine
Return non-nil if a buffer belongs to this target.  Used during
association when a file is loaded.  It is generally unecessary to
override this unless you keep auxilliary files.
@end table

These methods are used by the semantic package extentions @xref{(semantic)Top}.

@table @code
@item ede-buffer-header-file
Return a header file belonging to a given buffer.  Prototypes are place
there when appropriate
@item ede-buffer-documentation-files
Return the documentation file information about this file would be
stored in.
@item ede-documentation
List all documentation a project or target is responsible for.
@end table

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

When a target needs to know if it will accept a source file, it
references its list of source code objects.  These objects then make
that decision.

Source code objects are stored in the target objects as a list of
symbols, where the symbols value is the object.  This enables the
project output mechanism to work more efficiently.

Here is an example for an instantiation of an Emacs Lisp source code object:

@example
(defvar ede-source-emacs
  (ede-sourcecode "ede-emacs-source"
		  :name "Emacs Lisp"
		  :sourcepattern "\\.el$"
		  :garbagepattern '("*.elc"))
  "Emacs Lisp source code definition.")
@end example

@xref{Sourcecode}.

@section Compiler and Linker objects

The EDE project class creates makefiles.  In order for a target to
create a @file{Makefile}, it must know how to compile the sources into
the program or desired data file, and possibly link them together.

A compiler object instantiation is used to link a given target with a
given source code type.  Some targets can handle many types of sources,
and thus has many compilers available to it.  Some targets may even have
multiple compilers for a given type of source code.

EDE will examine the actual source files in a target, cross reference
that against the compiler list to come up with the final set of
compilers that will be inserted into the Makefile.

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.

Compiler objects are stored in the target objects as a list of
symbols, where the symbols value is the object.  This enables the
project output mechanism to work more efficiently.

Targets will also have a special "compiler" slot which lets a user
explicitly choose the compiler they want to use.

Here is an example for texinfo:

@example
(defvar ede-makeinfo-compiler
  (ede-compiler
   "ede-makeinfo-compiler"
   :name "makeinfo"
   :variables '(("MAKEINFO" . "makeinfo"))
   :commands '("makeinfo -o $@ $<")
   :autoconf '(("AC_CHECK_PROG" . "MAKEINFO, makeinfo"))
   :sourcetype '(ede-makeinfo-source)
   )
  "Compile texinfo files into info files.")
@end example

@xref{Compilers}.

When creating compiler instatiations, it may be useful to @code{clone}
an existing compiler variable.

The second important object is the linker class.  The linker is similar
to the compiler, except several compilers might be used to create some
object files, and only one linker is used to link those objects together.

See @file{ede-proj-obj.el} for examples of the combination.

@section Class hierarchies

@menu
* Project    :: The different project types.
* Targets    :: The different target types.
* Sourcecode :: Source Code management types.
* Compilers  :: Compiler management types.
@end menu

@defindex pj
@defindex tg
@defindex sc
@defindex cm

@node Project, Targets, Extending EDE, Extending EDE

@include ede-projects.texi

@node Targets, Sourcecode, Project, Extending EDE

@include ede-targets.texi

@node Sourcecode, Compilers, Targets, Extending EDE

The source code type is an object designed to associated files with
targets.

@include ede-sourcecode.texi

@node Compilers, ,Sourcecode, Extending EDE

The compiler object is designed to associate source code with
compilers.  The target then references the compilers it can use.
When the makefile is created, this object type knows how to create
compile commands.

@include ede-compilers.texi

@bye
