Initial Commit

[packages] / xemacs-packages / ede / ede.texi

\input texinfo   @c -*-texinfo-*-
@c
@c $Id: ede.texi,v 1.1 2007-11-26 15:22:13 michaels 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, 2004, 2005 Eric M. Ludlam
@end titlepage

@contents

@node top, EDE Project Concepts, (dir), (dir)
@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 Project Concepts::        EDE Project Concepts
* 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.
* Project::                     
* Targets::                     
* Sourcecode::                  
* Compilers::                   

@detailmenu
 --- The Detailed Node Listing ---

Modifying your project

* Add/Remove target::           
* Add/Remove files::            
* Customize Features::          
* EDE Project Features::        

EDE Project Features

* Changing Compilers and Flags::  
* Configurations::              

Project types

* Make and Automake projects::  Project types of @samp{ede-project}
* Automake direct projects::    Project interface on hand-written automake files.

Extending EDE

* User interface methods::      Methods associated with keybindings
* Base project methods::        The most basic methods on EDE objects.
* Sourcecode objects::          Defining new sourcecode classes.
* Compiler and Linker objects::  Defining new compilers and linkers.

Class hierarchies

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

@end detailmenu
@end menu

@node EDE Project Concepts, EDE Mode, top, top
@chapter EDE Project Concepts

EDE is a generic interface for managing projects.  In other words,
there is one set of menus and keybindings specified by EDE, but there
are multiple ways a project can be expressed via a build system.

You can learn about multiple @ref{Project types}, or the specific
build or debug commands in other chapters.

In EDE, a project hierarchy matches a directory hierarchy.  There
would be a project root, and subprojects in different subdirectories.

Within each project, there can be multiple targets.  A target at the
simplest level is a named collection of files within a project.  There
are two important reasons for specifying a target.

@enumerate
@item
A collection of files to be added to a distribution.
@item
A collection of files that can be built into something else.
@end enumerate

If you intend to write code, and have it tarred up and distributed
under the GPL, all important files must be a part of some target so
that they will be added to the distribution file.

Targets that are lists of files that can be built into something else
will also be distributed, but the build process will also convert
those files into some specified built thing, such as a program or
compiled documentation.

Lastly, EDE provides a way for other tools to easilly learn file
associations.  For example, a program might need to restrict some sort
of search to files in a single target, or need to discover the
location of documentation or interface files.  EDE can provide this
information.

@node EDE Mode, Creating a project, EDE Project Concepts, 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

To create a new project, first load a file you would want in that
project into a buffer.  If you have a hierarchy of directories, choose
a file in the topmost directory first.  From this buffer, run
@command{ede-new}.

EDE can support several types of projects.  When creating a new
project with the command @command{ede-new} 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 @emph{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 by making an
@emph{Automake} project with @command{ede-new}.  The other is to just write
some automake files which EDE with automatically detect this, and put
you into a different Automake mode.  Any GNU project using Automake
will be detected in this way, and you can use EDE to modify those
Makefiles for you.

@section Creating a subproject

A subproject is merely a project in a subdirectory of another project.
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

Your project and targets are systems with lots of options.  Generic
features are listed here.  You will need to read sections on specific
project types for detailed information on the project you might be
using.

@menu
* Add/Remove target::           
* Add/Remove files::            
* Customize Features::          
* EDE Project Features::        
@end menu

@node Add/Remove target, Add/Remove files, Modifying your project, Modifying your project
@section Add/Remove target

A project with no targets isn't very useful, so you can use EDE to add
and remove targets from your project.

You can create a new target with the @command{ede-new-target} command
@kbd{C-c . t}.  If appropriate you will be given the option to add the
current buffer into the newly created target.

When creating a target, you will be given an option list of target
types.  Each target type will have its own build process and class of
files it will accept.

You can remove a target with the command @code{ede-delete-target}.

The add and remove commands are in the @samp{Project->Project Options}
menu.

@node Add/Remove files, Customize Features, Add/Remove target, Modifying your project
@section Add/Remove files

A target with no files isn't very useful, so you can use EDE to add
and remove files to targets.  Sometimes files can belong to multiple
targets, and that is ok.

You can add files into targets with the command @command{ede-add-file}
bound to @kbd{C-c . a}.   If there are no targets created that you
wish to use, you can type in @samp{new target} to create a new target
apropriate for the file you are adding.

You can remove files from a target with the @command{ede-remove-file}
bound to @kbd{C-c . d}.  If the file is in multiple targets, it will
query for every target it could be removed from.

When you are working in a project, if you load a new file into a
buffer that is not a part of an active target, EDE will automatically
remind you to add it to a target of your choosing.  If you do not wish
to add it to a target, you can choose @samp{none}.  You can customize
the behavior with the variable @command{ede-auto-add-method}.

@node Customize Features, EDE Project Features, Add/Remove files, Modifying your project
@section Customize Features

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.

If the 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 current project or target into a @emph{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 EDE Project Features,  , Customize Features, Modifying your project
@section EDE Project Features

This section details user facing features of an EDE @samp{Make} style
project.  The specified options may be the same as in a
@samp{Automake} project, but are not the same as in an direct Automake
project.

To modify any of the specific features mentioned here, you need to
customize the project or target with @command{customize-project} or
@command{customize-target}.

When you are customizing, you are directly manipulating slot values in
EIEIO objects.  If you are interested in additional details, see
@ref{Extending EDE}

@menu
* Changing Compilers and Flags::  
* Configurations::              
@end menu

@node Changing Compilers and Flags, Configurations, EDE Project Features, EDE Project Features
@subsection Changing Compilers and Flags

Targets that build stuff need compilers.  To change compilers, you
need to customize the desired target.

In the @samp{[Make]} section, you can then choose a new compiler or
linker from the list.  If a linker you need is not available, you will
need to create a new one.  @ref{Compiler and Linker objects}.

If an existing compiler or linker is close, but you need to modify
some flag set such as adding an include path you will need to add a
configuration variable.

To start, you should create the basic setup, and construct a makefile
with @command{ede-proj-regenerate}.  Look in the @file{Makefile} to
see what commands are inserted.  Once you have determined the variable
you need to modify, you can add a configuration for it.
@ref{Configurations}.

@node Configurations,  , Changing Compilers and Flags, EDE Project Features
@subsection Configurations

Configurations specify different ways to build a project.  For
example, you may configure a project to be in ``debug'' mode, or
perhaps in ``release'' mode.

The project, and each target type all have a slot named
@code{configuration-variables}.  To add new variables to a
configuration find this slot in the custom buffer, and insert a new
configuration.  Name it either ``debug'' or ``release'', then insert
some number of name/value pairs to it.

You can have any number of valid configurations too.  To add a new
configuration, customize your project.  Work in the @samp{[Settings]}
block for ``configurations''.  Add a new named configuration here.

To switch between different active conifigurations, modify the
``configuration default'' slot.

@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

These commands, plus project or target specific options are available
in the @samp{Project} menu.

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

@section Rescan

If you opt to go in and edit EDE project files directly, perhaps with
the @command{ede-edit-file-target}, you will need to have Emacs rescan
the project files to update the internal data structures.

Use @command{ede-rescan-toplevel} bound to @kbd{C-c . g} to refresh
your system.

@section Speedbar

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}.  This is bound to @kbd{C-c . s}.

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

The other is project type handles automake projects directly from the
automake files.  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

@menu
* Make and Automake projects::  Project types of @samp{ede-project}
* Automake direct projects::    Project interface on hand-written automake files.
@end menu

@node Make and Automake projects, Automake direct projects, Project types, Project types
@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 configureation 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 improt and maintain a configure.am script and a
host of other files required by Automake.

@node Automake direct projects,  , Make and Automake projects, Project types
@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 Extending EDE, Project, Project types, top
@chapter Extending EDE

This chapter is intended for users who want to write new parts or fix
bugs in EDE.  A knowledge of Emacs Lisp, and some EIEIO(CLOS) is
required.

EDE's dependance on EIEIO, the CLOS package for Emacs 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,
@ref{Project types}.  @ref{(eieio)Top}. For details on using EIEIO to
extending classes, and writing methods.

If you intend to exted EDE, 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} instead.  You may want to also add
new fields to track important information.

If you are building currently unsuported code into a program or shared
library, it is unlikely you need a new target at all.  Instead you
would need to create a new compiler or linker object that compiles
source code of the desired type. @ref{Compiler and Linker objects}.

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.el} are two interesting
examples.

@menu
* User interface methods::      Methods associated with keybindings
* Base project methods::        The most basic methods on EDE objects.
* Sourcecode objects::          Defining new sourcecode classes.
* Compiler and Linker objects::  Defining new compilers and linkers.
@end menu

@node User interface methods, Base project methods, Extending EDE, Extending EDE
@section User interface methods

These methods are core behaviors associated with user commands.
If you do not implement a method, there is a resonable default that
may do what you need.

@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.
@item project-debug-target
What to do when a user wants to debug your target.
@item project-update-version
Easily update 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

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

@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
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 symbol's value is the object.  This enables the
project save file mechanism to work.

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

If you want to recycle parts of an existing sourcecode object, you can
clone the original, and then just tweak the parts that are different.
For example:

@example
(defvar ede-source-emacs-autoload
  (clone ede-source-emacs "ede-source-emacs-autoload"
         :name "Emacs Lisp Autoload"
         :sourcepattern "-loaddefs\\.el")
  "Emacs Lisp autoload source code.")
@end example

In this case, the garbage pattern is the same.

@xref{Sourcecode}.

@node Compiler and Linker objects,  , Sourcecode objects, Extending EDE
@section Compiler and Linker objects

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 associate 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 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.  Cloning allows you to only modify
parts of the original, while keeping the rest of the same.
Modification of the original will result in the clone also being
changed for shared value slots.

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, top
@chapter Project

@include ede-projects.texi

@node Targets, Sourcecode, Project, top
@chapter Targets

@include ede-targets.texi

@node Sourcecode, Compilers, Targets, top
@chapter Sourcecode

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

@include ede-sourcecode.texi

@node Compilers,  , Sourcecode, top
@chapter Compilers

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