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

 1. A collection of files to be added to a distribution.

 2. A collection of files that can be built into something else.

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.

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

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

EDE can support several types of projects.  When creating a new project with the command ede-new 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 by making an Automake project with 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.

Creating a subproject
=====================

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

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.

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 ede-new-target command 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 ede-delete-target.

The add and remove commands are in the Project->Project Options menu.

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 ede-add-file bound to C-c . a.   If there are no targets created that you wish to use, you can type in new target to create a new target apropriate for the file you are adding.

You can remove files from a target with the ede-remove-file bound to 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 none.  You can customize the behavior with the variable ede-auto-add-method.

Customize Features
==================

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.

If the 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 current project or target into a 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.

EDE Project Features
====================

This section details user facing features of an EDE Make style project.  The specified options may be the same as in a 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 customize-project or customize-target.

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

Changing Compilers and Flags
----------------------------

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

In the [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.  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 ede-proj-regenerate.  Look in the Makefile to see what commands are inserted.  Once you have determined the variable you need to modify, you can add a configuration for it. Configurations.

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 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 [Settings] block for ``configurations''.  Add a new named configuration here.

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

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.

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

Miscellaneous commands
**********************

Rescan
======

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

Use ede-rescan-toplevel bound to C-c . g to refresh your system.

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 ede-speedbar.  This is bound to C-c . s.

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.

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 ede-project in Automake mode to have EDE create Makefile.am file, and a configure.in file.

Make and Automake projects
==========================

A project of ede-project type creates a file called Project.ede in every project directory.  This is used to track your configureation information.  If you configure this project to be in Makefile mode, then this project will autogenerate a Makefile.  If you configure it in Automake mode a 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.

Automake direct projects
========================

The project type that reads Makefile.am directly is derived from the sources of the original project-am.el mode that was distributed independently.  This mode eventually became EDE.  The 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.

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, Project types.  (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 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 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. Compiler and Linker objects.

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

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.

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.

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

project-update-version
     Easily update 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 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:

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

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:

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

In this case, the garbage pattern is the same.

See Sourcecode.

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

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 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 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.  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 ede-proj-obj.el for examples of the combination.

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

Project
*******

     [file ede-projects.texi not included]

Targets
*******

     [file ede-targets.texi not included]

Sourcecode
**********

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

     [file ede-sourcecode.texi not included]

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.

     [file ede-compilers.texi not included]