     START-INFO-DIR-ENTRY
     * ede: (ede).       Objects for Emacs
     END-INFO-DIR-ENTRY

EDE is a collection of definitions called the 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.

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 global-ede-mode, or by putting this in your ~/.emacs file.

     (require 'ede)
     (global-ede-mode t)

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

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. See 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 Make.  A derivation of this is the 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 ede-project class, and the other through project-am class.  project-am will autoload in any GNU Automake based distribution that does not contain a Project.ede file.

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 ede-new command (or "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.

Modifying your project
**********************

A project, and it's targets, are objects using the EIEIO object system. See (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 ede-new-target command C-c . t.  Once created, you can now put source files into this target.  You can remove a target with the command ede-delete-target.

You can add and remove files into targets with the command ede-add-file and ede-remove-file bound to C-c . a and 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 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 customize-project or 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 ede-edit-file-target bound to C-c . e.

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.

C-c . c
     Compile the current target.

C-c . C
     Compile the entire project.

c-c . D
     Debug the current target.

ede-make-dist
     Build a distribution file for your project.

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 ede-speedbar.

Project types
*************

There are two types of project modes currently.  One is ede-project, and shows up as Make and Automake when creating new projects.  ede-project lives in the file ede-proj.  The other is project type lives in 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 ede-project in Automake mode to have EDE create Makefile.am file, and a configure.in file.

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

The project type that reads Makefile.am directly is derived from the sources of the original 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.

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, see Project types.  See (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 ede-project class, and it's targets.  See project-am.el for basic details on adding targets to it.

For the ede-project type, the core target class is called 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 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 ede-skel.el file for examples of these.  The files ede-proj-info.el and ede-proj-elisp are two interesting examples.

User interface methods
======================

These methods are core behaviors associated with user commands.

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.

project-remove-file
     Reverse of project-add-file.

project-compile-target
     Override this if you want to do something special when the user "compiles" this target.  The default is probably fine.

project-debug-target
     What to do when a user wants to debug your target.

project-update-version
     Easily updated the version number of your project.

project-edit-file-target
     Edit the file the project's information is stored in.

project-new-target
     Create a new target in a project.

project-delete-target
     Delete a target from a project.

project-make-dist
     Make a distribution (tar archive) of the project.

project-rescan
     Rescan a project file, changing the data in the existing objects.

Base project methods
====================

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

ede-name
     Return a string that is the name of this target.

ede-target-name
     Return a string that is the name of the target used by a Make system.

ede-description
     A brief description of the project or target.  This is currently used by the ede-speedbar interface.

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.

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.

These methods are used by the semantic package extentions see (semantic)Top.

ede-buffer-header-file
     Return a header file belonging to a given buffer.  Prototypes are place there when appropriate

ede-buffer-documentation-files
     Return the documentation file information about this file would be stored in.

ede-documentation
     List all documentation a project or target is responsible for.

Sourcecode objects
==================

EDE projects track source file / target associates via source code objects.  The definitions for this is in 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 .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:

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

See Sourcecode.

Compiler and Linker objects
===========================

The EDE project class creates makefiles.  In order for a target to create a 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 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:

     (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.")

See Compilers.

When creating compiler instatiations, it may be useful to 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 ede-proj-obj.el for examples of the combination.

Class hierarchies
=================

     [file ede-projects.texi not included]

     [file ede-targets.texi not included]

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

     [file ede-sourcecode.texi not included]

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.

     [file ede-compilers.texi not included]