EDE

EDE is the Emacs Development Environment: an Emacs extension that simplifies building and debugging programs in Emacs. It attempts to emulate a typical IDE (Integrated Development Environment). EDE can manage or create your makefiles and other building environment duties, allowing you to concentrate on writing code rather than support files. It aims to make it much easier for new programmers to learn and adopt GNU ways of doing things.

This file describes EDE, the Emacs Development Environment.

Copyright © 1998–2001, 2004–2005, 2008–2024 Free Software Foundation, Inc.

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

Table of Contents

Next: , Previous: , Up: EDE   [Contents]

1 EDE Project Concepts

EDE is a generic interface for managing projects. It specifies a single set of menus and key bindings, while supporting multiple ways to express a project via a build system.

In the subsequent chapters, we will describe the different project types (see Creating a project), as well as the commands to build and debug projects (see Building and Debugging).

In EDE, a project hierarchy matches a directory hierarchy. The project’s topmost directory is called the project root, and its subdirectories are subprojects.

Each project can contain multiple targets. A target, at the simplest level, is a named collection of files within a project. A target can specify two different types of information:

  1. A collection of files to be added to a distribution (e.g., a tarball that you intend to distribute to others).
  2. A collection of files that can be built into something else (e.g., a program or compiled documentation).

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

Next: , Previous: , Up: EDE   [Contents]

2 EDE Mode

EDE is implemented as a minor mode, which augments other modes such as C mode, and Texinfo mode. You can enable EDE for all buffers by running the command global-ede-mode, or by putting this in your init file: 

(global-ede-mode t)

Activating EDE adds a menu named ‘Development’ to the menu bar. This menu provides several menu items for high-level EDE commands. These menu items, and their corresponding key bindings, are independent of the type of project you are actually working on.

Next: , Previous: , Up: EDE   [Contents]

3 Quick Start

Once you have EDE enabled, you can create a project. This chapter provides an example C++ project that will create Automake files for compilation.

3.1 Step 1: Create root directory

First, lets create a directory for our project. For this example, we’ll start with something in /tmp. 

C-x C-f /tmp/myproject/README RET
M-x make-directory RET RET

Now put some plain text in your README file to start.

Now, lets create the project: 

M-x ede-new RET Automake RET myproject RET

Nothing visible happened, but if you use dired to look at the directory, you should see this: 

  /tmp/myproject:
  total used in directory 32 available 166643476
  drwxr-xr-x  2 zappo users  4096 2012-02-23 22:10 .
  drwxrwxrwt 73 root  root  20480 2012-02-23 22:10 ..
  -rw-r--r--  1 zappo users   195 2012-02-23 22:10 Project.ede
  -rw-r--r--  1 zappo users    10 2012-02-23 22:09 README

3.2 Step 2: Create Subdirectories and Files

We’ll make a more complex project, so use dired to create some more directories using the + key, and typing in new directories: 

+ include RET
+ src RET

Now I’ll short-cut in this tutorial. Create the following files:

include/myproj.hh 

/** myproj.hh ---
 */

#ifndef myproj_hh
#define myproj_hh 1

#define IMPORTANT_MACRO 1

int my_lib_function();

#endif // myproj_hh

src/main.cpp 

/** main.cpp ---
 */

#include <iostream>
#include "myproj.hh"

int main() {

}

#ifdef IMPORTANT_MACRO
int my_fcn() {

}
#endif

src/mylib.cpp 

/** mylib.cpp ---
 *
 * Shared Library to build
 */

int my_lib_function() {

}

3.3 Step 3: Create subprojects

EDE needs subdirectories to also have projects in them. You can now create those projects.

With main.cpp as your current buffer, type: 

M-x ede-new RET Automake RET src RET

and in myproj.hh as your current buffer, type: 

M-x ede-new RET Automake RET include RET

These steps effectively only create the Project.ede file in which you will start adding targets.

3.4 Step 4: Create targets

In order to build a program, you must have targets in your EDE Projects. You can create targets either from a buffer, or from a dired directory buffer.

Note: If for some reason a directory list buffer, or file does not have the ‘Project’ menu item, or if EDE key bindings don’t work, just use M-x revert-buffer RET to force a refresh. Sometimes creating a new project doesn’t restart buffers correctly.

Lets start with the header file. In include/myproj.hh, you could use the menu, but we will now start using the EDE command prefix which is C-c .. 

C-c . t includes RET miscellaneous RET y

This creates a misc target for holding your includes, and then adds myproj.hh to the target. Automake (the tool) has better ways to do this, but for this project, it is sufficient.

Next, visit the src directory using dired. There should be a ‘Project’ menu. You can create a new target with 

. t myprogram RET program RET

Note that . t is a command for creating a target. This command is also in the menu. This will create a target that will build a program. If you want, visit Project.ede to see the structure built so far.

Next, place the cursor on main.cpp, and use . a to add that file to your target. 

. a myprogram RET

Note that these prompts often have completion, so you can just press TAB to complete the name myprogram.

If you had many files to add to the same target, you could mark them all in your dired buffer, and add them all at the same time.

Next, do the same for the library by placing the cursor on mylib.cpp. 

. t mylib RET sharedobject RET
. a mylib RET

3.5 Step 5: Compile, and fail

Next, we’ll try to compile the project, but we aren’t done yet, so it won’t work right away.

Visit /tmp/myproject/Project.ede. We’re starting here because we don’t have any program files in this directory yet. Now we can use the compile command: 

C-c . C

Because this is the very first time, it will create a bunch of files for you that are required by Automake. It will then use automake to build the support infrastructure it needs. This step is skipped if you choose just a Makefile build system.

After the Automake init, it runs compile. You will immediately discover the error in main.cpp can’t find myproj.hh. We need to go fix this.

3.6 Step 6: Customizing your project

To fix the failed compile, we need to add /tmp/myproject/include to the include path.

Visit main.cpp. 

M-x customize-project RET

Select the ‘[Settings]’ subgroup of options. Under ‘Variable :’ click ‘[INS]’. At this point, you need to be somewhat savvy with Automake. Add a variable named ‘CPPFLAGS’, and set the value to ‘../include’.

You should see something like this: 

Variables :
[INS] [DEL] Cons-cell:
            Name: AM_CPPFLAGS
            Value: -I../include
[INS]
Variables to set in this Makefile.

Click ‘[Apply]’. Feel free to visit Project.ede to see how it changed the config file.

Compile the whole project again with C-c . C from main.cpp. It should now compile.

3.7 Step 7: Shared library dependency

Note: Supporting shared libraries for Automake in this way is easy, but doing so from a project of type Makefile is a bit tricky. If you are creating shared libraries too, stick to Automake projects.

Next, lets add a dependency from main.cpp on our shared library. To do that, update main like this: 

int main() {

  my_lib_function();

}

Now compile with: 

C-c . c

where the lower case c compiles just that target. You should see an error.

This time, we need to add a dependency from main.cpp on our shared library. To do that, we need to customize our target instead of the project. This is because variables such as the include path are treated globally, whereas dependencies for a target are target specific. 

M-x customize-target RET

On the first page, you will see an Ldlibs-local section. Add mylib to it by first clicking ‘[INS]’, and they adding the library. It should look like this: 

Ldlibs-Local :
[INS] [DEL] Local Library: libmylib.la
[INS]
Libraries that are part of this project. [Hide Rest]
The full path to these libraries should be specified, such as:
../lib/libMylib.la  or ../ar/myArchive.a

You will also see other variables for library related flags and system libraries if you need them. Click ‘[Accept]’, and from main.cpp, again compile the whole project to force all dependent elements to compile: 

C-c . C

3.8 Step 8: Run your program

You can run your program directly from EDE. 

C-c . R RET RET

If your program takes command line arguments, you can type them in when it offers the command line you want to use to run your program.

Next: , Previous: , Up: EDE   [Contents]

4 Creating a project

To create a new project, first visit a file that you want to include in that project. If you have a hierarchy of directories, first visit a file in the topmost directory. From this buffer, type M-x ede-new, or click on the ‘Create Project’ item in the ‘Development’ menu.

The ede-new command prompts for the type of project you would like to create. Each project type has its own benefits or language specific enhancements. Not all projects that EDE supports also allow creating a new project. Projects such as emacs or linux are designed to recognize existing projects only. Project types such as ‘Make’ and ‘Automake’ do support creating new project types with ede-new.

A subproject is merely a project in a subdirectory of another project. You can create a subproject by using the ede-new command (or the ‘Create Project’ menu item), while visiting a buffer in a subdirectory of the project root. This new project is automatically added to the parent project, and will be automatically loaded when EDE reads the parent project.

When using a project command that involves 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 dependent on that project’s type.

Next: , Previous: , Up: EDE   [Contents]

5 Modifying your project

In this chapter, we describe the generic features for manipulating projects, including the targets and files within them. Subsequent chapters, which describe specific project types, will provide more detailed information about exactly what these features do.

Next: , Up: Modifying your project   [Contents]

5.1 Add/Remove target

To create a new target, type C-c . t (ede-new-target) or use the ‘Add Target’ menu item in the ‘Project Options’ submenu. This prompts for a target name, and adds the current buffer to that target.

The ede-new-target command also prompts for a target type. Each target type has its own build process and class of files that it will accept.

To remove a target from the project, type M-x ede-delete-target, or use the ‘Remove Target’ menu item in the ‘Project Options’ submenu.

Next: , Previous: , Up: Modifying your project   [Contents]

5.2 Add/Remove files

To add the current file to an existing target, type C-c . a (ede-add-file), or use the ‘Add File’ menu item in the ‘Target Options’ submenu.

You can add a file to more than one target; this is OK.

To remove the current file from a target, type C-c . d (ede-remove-file), or use the ‘Remove File’ menu item in the ‘Target Options’ submenu. If the file belongs to multiple targets, this command prompts for each target it could be removed from.

While working in a project, if you visit a file that is not part of an existing target, EDE automatically prompts for a target. If you do not wish to add the file to any target, you can choose ‘none’. You can customize this behavior with the variable ede-auto-add-method.

Next: , Previous: , Up: Modifying your project   [Contents]

5.3 Customize Features

A project, and its targets, are objects using the ‘EIEIO’ object system. See EIEIO manual. 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 loads the current project or target into a customization buffer, where you can tweak individual slots. This is usually necessary for complex projects.

Some project modes do not have a project file, but directly read a Makefile or other existing file. Instead of directly editing the object, you can edit the file by typing C-c . e (ede-edit-file-target). You should “rescan” the project afterwards (see Miscellaneous commands).

Next: , Previous: , Up: Modifying your project   [Contents]

5.4 Project Local Variables

EDE projects can store and manager project local variables. The variables are stored in the project, and will be restored when a project reloads.

Projects which are not stored on disk WILL NOT restore your project local variables later.

You can use Customize Features to of the project to edit the project local variables. They are under the ’Settings’ group as “Project Local Variables”.

You can also use M-x ede-set to set a new variable local in the mini buffer.

In multi-level projects such as Automake and Make generating projects, project local variables are installed from both the TOP most project, and the local directory’s project. In that way, you can have some variables across your whole project, and some specific to a subdirectory.

You can use project local variables to set any Emacs variable so that buffers belonging to different projects can have different settings.

NOTE: When you use project-local variables with ede-cpp-root, the format is an association list. For example: 

(ede-cpp-root-project "SOMENAME"
                       :file "/dir/to/some/file"
                       :local-variables
                       '((grep-command . "grep -nHi -e ")
                         (compile-command . "make -f MyCustomMakefile all")))

Previous: , Up: Modifying your project   [Contents]

5.5 EDE Project Features

This section details user facing features of an EDE ‘Make’ style project. An ‘Automake’ project has similar options (but a direct Automake project does not).

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. See Extending EDE, if you are interested in additional details.

Next: , Up: EDE Project Features   [Contents]

5.5.1 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 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. See 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. See Configurations.

Previous: , Up: EDE Project Features   [Contents]

5.5.2 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 configurations, modify the “configuration default” slot.

Next: , Previous: , Up: EDE   [Contents]

6 Building and Debugging

EDE provides the following “project-aware” compilation and debugging commands:

C-c . c

Compile the current target (ede-compile-target).

C-c . C

Compile the entire project (ede-compile-project).

c-c . D

Debug the current target (ede-debug-target).

M-x ede-make-dist

Build a distribution file for your project.

These commands are also available from the ‘Development’ menu.

Next: , Previous: , Up: EDE   [Contents]

7 Miscellaneous commands

If you opt to go in and edit EDE project files directly—for instance, by using C-c . e (see Customize Features)—you must then “rescan” the project files to update the internal data structures. To rescan the current project, type C-c . g (ede-rescan-toplevel).

EDE can help you find files in your project, via the command C-c . f (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 ede-locate-setup-options.

Variable: 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 ede-locate-base is at end of the list.

EDE also provides a project display mode for the speedbar (see Speedbar in 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 C-c . s (ede-speedbar).

Next: , Up: Miscellaneous commands   [Contents]

7.1 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 configuration 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 import and maintain a configure.am script and a host of other files required by Automake.

Next: , Previous: , Up: Miscellaneous commands   [Contents]

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

Previous: , Up: Miscellaneous commands   [Contents]

7.3 Simple Projects

There is a wide array of simple projects. In this case a simple project is one that detects, or is directed to identify a directory as belonging to a project, but doesn’t provide many features of a typical EDE project. Having the project however allows tools such as Semantic to find sources and perform project level completions.

Next: , Up: Simple Projects   [Contents]

7.3.1 ede-cpp-root

The ede-cpp-root project type allows you to create a single object with no save-file in your .emacs file. It allows EDE to provide the Semantic package with the ability to find header files quickly.

The 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 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 .emacs file, modifying appropriate bits as needed. 

(ede-cpp-root-project "SOMENAME" :file "/dir/to/some/file")

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

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: 

(ede-cpp-root-project "NAME" :file "FILENAME"
    :include-path '( "/include" "../include" "/c/include" )
    :system-include-path '( "/usr/include/c++/3.2.2/" )
    :compile-command "make compile"
    :spp-table '( ("MOOSE" . "")
                  ("CONST" . "const") ) )

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 :header-match-regexp to change it.

The :system-include-path allows you to specify absolute names of include directories where system header files can be found. These will be applied to files in this project only.

With :compile-command you can provide a command which should be run when calling ede-compile-project.

The :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 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 :spp-files to a list of file names relative to the root of your project. Specifying this is like setting the variable 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: 

(ede-cpp-root-project "NAME" :file "FILENAME" :locate-fcn 'MYFCN)

Where MYFCN is a symbol for a function. The locate function can be used in place of 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:

NAME

The name of the file to find.

DIR

The directory root for this cpp-root project.

When creating a project with ede-cpp-root, you can get additional configurations via Project Local Variables. Be aware that the format for project local variables is an association list. You cannot use 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 .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 ede-project-class-files list, and also provide two functions to teach EDE how to load your project pattern

It would look like this: 

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

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

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

Next: , Previous: , Up: Simple Projects   [Contents]

7.3.2 ede-emacs

The ede-emacs project automatically identifies an Emacs source tree, and enables EDE project mode for it.

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

Next: , Previous: , Up: Simple Projects   [Contents]

7.3.3 ede-linux

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

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

Through the variables project-linux-build-directory-default and project-linux-architecture-default, you can set the build directory and its architecture, respectively. The default is to assume that the build happens in the source directory and to auto-detect the architecture; if the auto-detection fails, you will be asked.

Next: , Previous: , Up: Simple Projects   [Contents]

7.3.4 ede-generic-project

The ede-generic-project is a project system that makes it easy to wrap up different kinds of build systems as an EDE project. Projects such as ede-emacs require coding skills to create. Generic projects also require writing Emacs Lisp code, but the requirements are minimal. You can then use customize-project to configure build commands, includes, and other options for that project. The configuration is saved in EDEConfig.el.

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

Command: ede-enable-generic-projects

Enable generic project loaders.

This enables generic loaders for projects that are detected using either a Makefile, SConstruct, or CMakeLists.

You do not need to use this command if you create your own generic project type.

If you want to create your own generic project loader, you need to define your own project and target classes, and create an autoloader. The example for Makefiles looks like this: 

;;; MAKEFILE

(defclass ede-generic-makefile-project (ede-generic-project)
  ((buildfile :initform "Makefile"))
  "Generic Project for makefiles.")

(cl-defmethod ede-generic-setup-configuration ((proj ede-generic-makefile-project) config)
  "Set up 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)

This example project will detect any directory with the 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.

Previous: , Up: Simple Projects   [Contents]

7.3.5 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 locate, or 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 ede-locate-setup-options with the names of different locate objects. Miscellaneous commands.

Configure this in your .emacs before loading in CEDET or EDE. If you want to add support for GNU Global, your configuration would look like this: 

(setq ede-locate-setup-options '(ede-locate-global ede-locate-base))

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 ede-locate-base. The subclass should also implement two methods. See the code in 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.

Next: , Previous: , Up: EDE   [Contents]

8 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 uses EIEIO, the CLOS package for Emacs, to 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. See EIEIO manual for details on using EIEIO to extending classes, and writing methods.

If you intend to extend 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 its 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 unsupported 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.

Next: , Up: Extending EDE   [Contents]

8.1 Development Overview

EDE is made up of a series of classes implemented with EIEIO. These classes define an interface that can be used to create different types of projects.

EDE defines two superclasses which are ede-project and ede-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.

Some example project types are:

project-am

Automake project which reads existing Automake files.

ede-proj-project

This project type will create Makefiles, or Makefile.am files to compile your project.

ede-linux

This project type will detect linux source trees.

ede-emacs

This project will detect an Emacs source tree.

There are several other project types as well.

The first class you need to know to create a new project type is ede-project-autoload. New instances of this class are needed to define how Emacs associates different files/buffers with different project types. All the autoloads are kept in the variable ede-project-class-files.

The next most important class to know is ede-project. This is the baseclass defines how all projects behave. The basic pattern for a project is that there is one project per directory, and the topmost project or directory defines the project as a whole.

Key features of ede-project are things like name and version number. It also holds a list of ede-target objects and a list of sub projects, or more ede-project objects.

New project types must subclass ede-project to add special behavior. New project types also need to subclass ede-target to add specialty behavior.

In this way, the common EDE interface is designed to work against ede-project, and thus all subclasses.

ede-project subclasses ede-project-placeholder. This is the minimum necessary project needed to be cached between runs of Emacs. This way, Emacs can track all projects ever seen, without loading those projects into memory.

Here is a high-level UML diagram for the EDE system created with COGRE.. 

+-----------------------+        +-----------------------+
|                       |        |ede-project-placeholder|
|ede-project-class-files|        +-----------------------+
|                       |        +-----------------------+
+-----------------------+        +-----------------------+
           /\                                ^
           \/                               /_\
            |                                |
 +--------------------+                +-----------+         +----------+
 |ede-project-autoload|                |ede-project|         |ede-target|
 +--------------------+<>--------------+-----------+<>-------+----------+
 +--------------------+                +-----------+         +----------+
 +--------------------+                +-----------+         +----------+
                                             ^
                                            /_\
                                             |
                       +---------------------+-----------------+
                       |                     |                 |
                       |                     |                 |
                       |                     |                 |
              +----------------+   +-------------------+  +---------+
              |ede-proj-project|   |project-am-makefile|  |ede-emacs|
              +----------------+   +-------------------+  +---------+
              +----------------+   +-------------------+  +---------+
              +----------------+   +-------------------+  +---------+

Next: , Previous: , Up: Extending EDE   [Contents]

8.2 Detecting a Project

Project detection happens with the list of ede-project-autoload instances stored in ede-project-class-files. The full project detection scheme works like this:

Step 1:

find-file-hook calls ede-turn-on-hook on BUFFER.

Step 2:

ede-turn-on-hook turns on ede-minor-mode

Step 3:

ede-minor-mode looks to see if BUFFER is associated with any open projects. If not, it calls ede-load-project-file to find a project associated with the current directory BUFFER is in.

Step 4:

ede-minor-mode associates the found project with the current buffer with a series of variables, such as ede-object, and ede-object-project and ede-object-root-project.

Once a buffer is associated, EDE minor mode commands will operate on that buffer.

The function ede-load-project-file is at the heart of detecting projects, and it works by looping over all the known project autoload types in ede-project-autoload using the utility ede-directory-project-p.

The function ede-directory-project-p will call ede-dir-to-projectfile on every ede-project-autoload until one of them returns true. The method ede-dir-to-projectfile in turn gets the :proj-file slot from the autoload. If it is a string (i.e., a project file name), it checks to see if that exists in BUFFER’s directory. If it is a function, then it calls that function and expects it to return a file name or nil. If the file exists, then this directory is assumed to be part of a project, and ede-directory-project-p returns the instance of ede-project-autoload that matched.

If the current directory contains the file .ede-ignore then that directory is automatically assumed to contain no projects, even if there is a matching pattern. Use this type of file in a directory that may contain many other sub projects, but still has a Makefile of some sort.

If the current directory is a project, then EDE scans upwards till it finds the top of the project. It does this by calling ede-toplevel-project. If this hasn’t already been discovered, the directories as scanned upward one at a time until a directory with no project is found. The last found project becomes the project root. If the found instance of ede-project-autoload has a valid proj-root slot value, then that function is called instead of scanning the project by hand. Some project types have a short-cut for determining the root of a project, so this comes in handy.

Getting back to ede-load-project-file, this now has an instance of ede-project-autoload. It uses the load-type slot to both autoload in the project type, and to create a new instance of the project type found for the root of the project. That project is added to the global list of all projects. All subprojects are then created and assembled into the project data structures.

Next: , Previous: , Up: Extending EDE   [Contents]

8.3 User interface methods

These methods are core behaviors associated with user commands. If you do not implement a method, there is a reasonable 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.

Next: , Previous: , Up: Extending EDE   [Contents]

8.4 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 unnecessary 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 unnecessary to override this unless you keep auxiliary files.

These methods are used by the semantic package extensions. See Semantic manual.

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.

Next: , Previous: , Up: Extending EDE   [Contents]

8.5 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, (i.e., 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.

Next: , Previous: , Up: Extending EDE   [Contents]

8.6 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.ac 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 instantiations, 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.

Next: , Previous: , Up: Extending EDE   [Contents]

8.7 Project

Next: , Up: Project   [Contents]

8.7.1 ede-project-placeholder

Inheritance Tree:
eieio-speedbar
eieio-speedbar-directory-button
ede-project-placeholder
Children:

See ede-project.

Slots:
:name

Type: string
Default Value: "Untitled"

The name used when generating distribution files.

:version

Type: string
Default Value: "1.0"

The version number used when distributing files.

:directory

Type: string

Directory this project is associated with.

:file

Type: string

File name where this project is stored.

8.7.1.1 Specialized Methods

Method: ede--project-inode :AFTER proj

Get the inode of the directory project PROJ is in.

Method: ede-project-root :AFTER this

If a project knows its root, return it here. Allows for one-project-object-for-a-tree type systems.

Method: ede-find-subproject-for-directory :AFTER proj dir

Find a subproject of PROJ that corresponds to DIR.

Method: ede-project-root-directory :AFTER this &optional file

If a project knows its root, return it here. Allows for one-project-object-for-a-tree type systems. Optional FILE is the file to test. It is ignored in preference of the anchor file for the project.

Method: ede-project-force-load :AFTER this

Make sure the placeholder THIS is replaced with the real thing. Return the new object created in its place.

Method: project-interactive-select-target :AFTER this prompt

Make sure placeholder THIS is replaced with the real thing, and pass through.

Method: project-add-file :AFTER this file

Make sure placeholder THIS is replaced with the real thing, and pass through.

Next: , Previous: , Up: Project   [Contents]

8.7.2 ede-project

Inheritance Tree:
eieio-speedbar
eieio-speedbar-directory-button
ede-project-placeholder

See ede-project-placeholder.

ede-project
Children:

See ede-cpp-root-project, ede-emacs-project, ede-linux-project, ede-maven-project, See ede-simple-project, See ede-simple-base-project, See ede-proj-project, See project-am-makefile, See ede-step-project.

Slots:
:targets

Type: list

List of top level targets in this project.

:tool-cache

Type: list

List of tool cache configurations in this project. This allows any tool to create, manage, and persist project-specific settings.

:web-site-url

Type: string

URL to this projects web site. This is a URL to be sent to a web site for documentation.

:web-site-directory

A directory where web pages can be found by Emacs. For remote locations use a path compatible with ange-ftp. You can also use TRAMP for use with rcp & scp.

:web-site-file

A file which contains the website for this project. This file can be relative to slot web-site-directory. This can be a local file, use ange-ftp or TRAMP.

:ftp-site

Type: string

FTP site where this project’s distribution can be found. This FTP site should be in Emacs form, as needed by ange-ftp, but can also be of a form used by TRAMP for use with scp, or rcp.

:ftp-upload-site

Type: string

FTP Site to upload new distributions to. This FTP site should be in Emacs form as needed by ange-ftp. If this slot is nil, then use ftp-site instead.

:configurations

Type: list
Default Value: ("debug" "release")

List of available configuration types. Individual target/project types can form associations between a configuration, and target specific elements such as build variables.

:configuration-default

Default Value: "debug"

The default configuration.

:local-variables

Default Value: nil

Project local variables

8.7.2.1 Specialized Methods

Method: ede-preprocessor-map :AFTER this

Get the pre-processor map for project THIS.

Method: ede-subproject-relative-path :AFTER proj &optional parent-in

Get a path name for PROJ which is relative to the parent project. If PARENT is specified, then be relative to the PARENT project. Specifying PARENT is useful for sub-sub projects relative to the root project.

Method: eieio-speedbar-description :AFTER obj

Provide a speedbar description for OBJ.

Method: ede-map-any-target-p :AFTER this proc

For project THIS, map PROC to all targets and return if any non-nil. Return the first non-nil value returned by PROC.

Method: ede-map-subprojects :AFTER this proc

For object THIS, execute PROC on all direct subprojects. This function does not apply PROC to sub-sub projects. See also ede-map-all-subprojects.

Method: ede-convert-path :AFTER this path

Convert path in a standard way for a given project. Default to making it project relative. Argument THIS is the project to convert PATH to.

Method: ede-name :AFTER this

Return a short-name for THIS project file. Do this by extracting the lowest directory name.

Method: ede-set-project-variables :AFTER project &optional buffer

Set variables local to PROJECT in BUFFER.

Method: eieio-speedbar-derive-line-path :AFTER obj &optional depth

Return the path to OBJ. Optional DEPTH is the depth we start at.

Method: ede-map-all-subprojects :AFTER this allproc

For object THIS, execute PROC on THIS and all subprojects. This function also applies PROC to sub-sub projects. See also ede-map-subprojects.

Method: project-update-version :AFTER ot

The :version of the project OT has been updated. Handle saving, or other detail.

Method: ede-buffer-header-file :AFTER this buffer

Return nil, projects don’t have header files.

Method: ede-buffer-documentation-files :AFTER this buffer

Return all documentation in project THIS based on BUFFER.

Method: ede-map-targets :AFTER this proc

For object THIS, execute PROC on all targets.

Method: ede-buffer-mine :AFTER this buffer

Return non-nil if object THIS lays claim to the file in BUFFER.

Method: ede-object-keybindings :BEFORE this

Retrieves the slot keybindings from an object of class ede-project

Method: ede-description :AFTER this

Return a description suitable for the minibuffer about THIS.

Method: eieio-speedbar-object-children :AFTER this

Return the list of speedbar display children for THIS.

Method: project-make-dist :AFTER this

Build a distribution for the project based on THIS project.

Method: ede-system-include-path :AFTER this

Get the system include path used by project THIS.

Method: project-new-target-custom :AFTER proj

Create a new target. It is up to the project PROJ to get the name.

Method: ede-subproject-p :AFTER proj

Return non-nil if PROJ is a sub project.

Method: ede-expand-filename :AFTER this filename &optional force

Return a fully qualified file name based on project THIS. FILENAME should be just a filename which occurs in a directory controlled by this project. Optional argument FORCE forces the default filename to be provided even if it doesn’t exist.

Method: ede-menu-items-build :AFTER obj &optional current

Return a list of menu items for building project OBJ. If optional argument CURRENT is non-nil, return sub-menu code.

Method: ede-update-version-in-source :AFTER this version

Change occurrences of a version string in sources. In project THIS, cycle over all targets to give them a chance to set their sources to VERSION.

Method: project-new-target :AFTER proj &rest args

Create a new target. It is up to the project PROJ to get the name.

Method: project-compile-project :AFTER obj &optional command

Compile the entire current project OBJ. Argument COMMAND is the command to use when compiling.

Method: eieio-speedbar-object-buttonname :AFTER object

Return a string to use as a speedbar button for OBJECT.

Method: ede-map-project-buffers :AFTER this proc

For THIS, execute PROC on all buffers belonging to THIS.

Method: ede-expand-filename-impl :AFTER this filename &optional force

Return a fully qualified file name based on project THIS. FILENAME should be just a filename which occurs in a directory controlled by this project. Optional argument FORCE forces the default filename to be provided even if it doesn’t exist.

Method: eieio-done-customizing :AFTER proj

Call this when a user finishes customizing PROJ.

Method: ede-html-documentation :AFTER this

Return a list of HTML files provided by project THIS.

Method: ede-documentation :AFTER this

Return a list of files that provides documentation. Documentation is not for object THIS, but is provided by THIS for other files in the project.

Method: project-interactive-select-target :AFTER this prompt

Interactively query for a target that exists in project THIS. Argument PROMPT is the prompt to use when querying the user for a target.

Method: ede-target-in-project-p :AFTER proj target

Is PROJ the parent of TARGET? If TARGET belongs to a subproject, return that project file.

Method: ede-find-target :AFTER proj buffer

Fetch the target in PROJ belonging to BUFFER or nil.

Method: ede-add-subproject :AFTER proj-a proj-b

Add into PROJ-A, the subproject PROJ-B.

Method: ede-commit-project :AFTER proj

Commit any change to PROJ to its file.

Method: project-dist-files :AFTER this

Return a list of files that constitutes a distribution of THIS project.

Method: ede-object-menu :BEFORE this

Retrieves the slot menu from an object of class ede-project

Method: ede-commit-local-variables :AFTER proj

Commit change to local variables in PROJ.

Next: , Previous: , Up: Project   [Contents]

8.7.3 ede-cpp-root-project

Inheritance Tree:
eieio-speedbar
eieio-speedbar-directory-button
ede-project-placeholder

See ede-project-placeholder.

ede-project

See ede-project.

ede-cpp-root-project

No children

This class implements the ede-cpp-root project type. See ede-cpp-root, for information about using this project type.

Slots:
:include-path

Type: list
Default Value: ("/include" "../include/")

The default locate function expands filenames within a project. If a header file (.h, .hh, etc.) name is expanded, and the :locate-fcn slot is nil, then the include path is checked first, and other directories are ignored. For very large projects, this optimization can save a lot of time.

Directory names in the path can be relative to the current buffer’s default-directory (not starting with a /). Directories that are relative to the project’s root should start with a /, such as "/include", meaning the directory include off the project root directory.

:system-include-path

Type: list
Default Value: nil

The system include path for files in this project. C files initialized in an ede-cpp-root-project have their semantic system include path set to this value. If this is nil, then the semantic path is not modified.

:spp-table

Type: list
Default Value: nil

C Preprocessor macros for your files. Preprocessor symbols will be used while parsing your files. These macros might be passed in through the command line compiler, or are critical symbols derived from header files. Providing header files macro values through this slot improves accuracy and performance. Use :spp-files to use these files directly.

:spp-files

Type: list
Default Value: nil

C header file with Preprocessor macros for your files. The PreProcessor symbols appearing in these files will be used while parsing files in this project. See semantic-lex-c-preprocessor-symbol-map for more on how this works.

:header-match-regexp

Type: string
Default Value: "\\.\\(h\\(h\\|xx\\|pp\\|\\+\\+\\)?\\|H\\)$\\|\\<\\w+$"

Regexp used to identify C/C++ header files.

:locate-fcn

Type: (or null function)
Default Value: nil

The locate function can be used in place of ede-expand-filename so you can quickly customize your custom target to use specialized local routines instead of the EDE routines. The function symbol must take two arguments: NAME - The name of the file to find. DIR - The directory root for this cpp-root project.

It should return the fully qualified file name passed in from NAME. If that file does not exist, it should return nil.

8.7.3.1 Specialized Methods

Method: initialize-instance :AFTER this &rest fields

Make sure the :file is fully expanded.

Method: ede-preprocessor-map :AFTER this

Get the pre-processor map for project this.

Method: ede-cpp-root-header-file-p :AFTER proj name

Non-nil if in proj the filename name is a header.

Method: ede-system-include-path :AFTER this

Get the system include path used by project this.

Method: ede-expand-filename-impl :AFTER proj name

Within this project proj, find the file name. This knows details about or source tree.

Next: , Previous: , Up: Project   [Contents]

8.7.4 ede-simple-project

Inheritance Tree:
eieio-speedbar
eieio-speedbar-directory-button
ede-project-placeholder

See ede-project-placeholder.

ede-project

See ede-project.

ede-simple-project

No children

8.7.4.1 Specialized Methods

Method: ede-commit-project :AFTER proj

Commit any change to PROJ to its file.

Next: , Previous: , Up: Project   [Contents]

8.7.5 ede-simple-base-project

Inheritance Tree:
eieio-speedbar
eieio-speedbar-directory-button
ede-project-placeholder

See ede-project-placeholder.

ede-project

See ede-project.

ede-simple-base-project

No children

EDE Simple project base class. This one project could control a tree of subdirectories.

Next: , Previous: , Up: Project   [Contents]

8.7.6 ede-proj-project

Inheritance Tree:
eieio-speedbar
eieio-speedbar-directory-button
ede-project-placeholder

See ede-project-placeholder.

ede-project

See ede-project.

ede-proj-project

No children

Slots:
:makefile-type

Type: symbol
Default Value: Makefile

The type of Makefile to generate. Can be one of 'Makefile, ’Makefile.in, or ’Makefile.am. If this value is NOT 'Makefile, then that overrides the :makefile slot in targets.

:variables

Type: list
Default Value: nil

Variables to set in this Makefile.

:configuration-variables

Type: list
Default Value: ("debug" (("DEBUG" . "1")))

Makefile variables to use in different configurations. These variables are used in the makefile when a configuration becomes active.

:inference-rules

Default Value: nil

Inference rules to add to the makefile.

:include-file

Default Value: nil

Additional files to include. These files can contain additional rules, variables, and customizations.

:automatic-dependencies

Type: boolean
Default Value: t

Non-nil to do implement automatic dependencies in the Makefile.

:metasubproject

Type: boolean
Default Value: nil

Non-nil if this is a metasubproject. Usually, a subproject is determined by a parent project. If multiple top level projects are grouped into a large project not maintained by EDE, then you need to set this to non-nil. The only effect is that the dist rule will then avoid making a tar file.

8.7.6.1 Specialized Methods

Method: ede-proj-makefile-create :AFTER this mfilename

Create a Makefile for all Makefile targets in THIS. MFILENAME is the makefile to generate.

Method: ede-proj-makefile-insert-rules :AFTER this

Insert rules needed by THIS target.

Method: ede-proj-makefile-tags :AFTER this targets

Insert into the current location rules to make recursive TAGS files. Argument THIS is the project to create tags for. Argument TARGETS are the targets we should depend on for TAGS.

Method: ede-proj-makefile-insert-variables :AFTER this

Insert variables needed by target THIS.

Method: project-make-dist :AFTER this

Build a distribution for the project based on THIS target.

Method: ede-proj-makefile-insert-dist-rules :AFTER this

Insert distribution rules for THIS in a Makefile, such as CLEAN and DIST.

Method: ede-proj-makefile-insert-dist-dependencies :AFTER this

Insert any symbols that the DIST rule should depend on. Argument THIS is the project that should insert stuff.

Method: ede-proj-makefile-insert-subproj-rules :AFTER this

Insert a rule for the project THIS which should be a subproject.

Method: ede-proj-makefile-create-maybe :AFTER this mfilename

Create a Makefile for all Makefile targets in THIS if needed. MFILENAME is the makefile to generate.

Method: ede-proj-configure-test-required-file :AFTER this file

For project THIS, test that the file FILE exists, or create it.

Method: ede-proj-setup-buildenvironment :AFTER this &optional force

Setup the build environment for project THIS. Handles the Makefile, or a Makefile.am configure.ac combination. Optional argument FORCE will force items to be regenerated.

Method: ede-proj-makefile-garbage-patterns :AFTER this

Return a list of patterns that are considered garbage to THIS. These are removed with make clean.

Method: ede-proj-configure-synchronize :AFTER this

Synchronize what we know about project THIS into configure.ac.

Method: ede-proj-makefile-insert-variables-new :AFTER this

Insert variables needed by target THIS.

NOTE: Not yet in use! This is part of an SRecode conversion of EDE that is in progress.

Method: ede-proj-makefile-configuration-variables :AFTER this configuration

Return a list of configuration variables from THIS. Use CONFIGURATION as the current configuration to query.

Method: eieio-done-customizing :AFTER proj

Call this when a user finishes customizing this object. Argument PROJ is the project to save.

Method: ede-proj-configure-recreate :AFTER this

Delete project THIS’s configure script and start over.

Method: ede-proj-makefile-insert-user-rules :AFTER this

Insert user specified rules needed by THIS target. This is different from ede-proj-makefile-insert-rules in that this function won’t create the building rules which are auto created with automake.

Method: ede-proj-dist-makefile :AFTER this

Return the name of the Makefile with the DIST target in it for THIS.

Method: ede-proj-configure-file :AFTER this

The configure.ac script used by project THIS.

Method: ede-commit-project :AFTER proj

Commit any change to PROJ to its file.

Method: project-dist-files :AFTER this

Return a list of files that constitutes a distribution of THIS project.

Method: ede-commit-local-variables :AFTER proj

Commit change to local variables in PROJ.

Next: , Previous: , Up: Project   [Contents]

8.7.7 project-am-makefile

Inheritance Tree:
eieio-speedbar
eieio-speedbar-directory-button
ede-project-placeholder

See ede-project-placeholder.

ede-project

See ede-project.

project-am-makefile

No children

8.7.7.1 Specialized Methods

Method: project-am-subtree :AFTER ampf subdir

Return the sub project in AMPF specified by SUBDIR.

Method: project-targets-for-file :AFTER proj

Return a list of targets the project PROJ.

Method: project-new-target :AFTER proj &optional name type

Create a new target named NAME. Argument TYPE is the type of target to insert. This is a string matching something in project-am-type-alist or type class symbol. Despite the fact that this is a method, it depends on the current buffer being in order to provide a smart default target type.

Previous: , Up: Project   [Contents]

8.7.8 ede-step-project

Inheritance Tree:
eieio-speedbar
eieio-speedbar-directory-button
ede-project-placeholder

See ede-project-placeholder.

ede-project

See ede-project.

ede-step-project

No children

Slots:
:init-variables

Type: list
Default Value: nil

Variables to set in this Makefile, at top of file.

:additional-variables

Type: (or null list)
Default Value: nil

Arbitrary variables needed from this project. It is safe to leave this blank.

:additional-rules

Type: (or null list)
Default Value: nil

Arbitrary rules and dependencies needed to make this target. It is safe to leave this blank.

:installation-domain

Type: symbol
Default Value: user

Installation domain specification. The variable GNUSTEP_INSTALLATION_DOMAIN is set at this value.

:preamble

Type: (or null list)
Default Value: ("GNUmakefile.preamble")

The auxiliary makefile for additional variables. Included just before the specific target files.

:postamble

Type: (or null list)
Default Value: ("GNUmakefile.postamble")

The auxiliary makefile for additional rules. Included just after the specific target files.

:metasubproject

Type: boolean
Default Value: nil

Non-nil if this is a metasubproject. Usually, a subproject is determined by a parent project. If multiple top level projects are grouped into a large project not maintained by EDE, then you need to set this to non-nil. The only effect is that the dist rule will then avoid making a tar file.

8.7.8.1 Specialized Methods

Method: ede-proj-makefile-create :AFTER this mfilename

Create a GNUmakefile for all Makefile targets in THIS. MFILENAME is the makefile to generate.

Method: project-make-dist :AFTER this

Build a distribution for the project based on THIS target.

Method: ede-proj-makefile-create-maybe :AFTER this mfilename

Create a Makefile for all Makefile targets in THIS if needed. MFILENAME is the makefile to generate.

Method: ede-proj-setup-buildenvironment :AFTER this &optional force

Setup the build environment for project THIS. Handles the Makefile, or a Makefile.am configure.ac combination. Optional argument FORCE will force items to be regenerated.

Method: eieio-done-customizing :AFTER proj

Call this when a user finishes customizing this object. Argument PROJ is the project to save.

Method: ede-proj-dist-makefile :AFTER this

Return the name of the Makefile with the DIST target in it for THIS.

Method: ede-commit-project :AFTER proj

Commit any change to PROJ to its file.

Method: project-dist-files :AFTER this

Return a list of files that constitutes a distribution of THIS project.

Method: ede-commit-local-variables :AFTER proj

Commit change to local variables in PROJ.

Next: , Previous: , Up: Extending EDE   [Contents]

8.8 Targets

Next: , Up: Targets   [Contents]

8.8.1 ede-target

Inheritance Tree:
eieio-speedbar
eieio-speedbar-directory-button
ede-target
Children:

ede-cpp-root-target, ede-emacs-target-c, ede-emacs-target-el, ede-emacs-target-misc, ede-linux-target-c, ede-linux-target-misc, ede-maven-target-java, ede-maven-target-c, ede-maven-target-misc, ede-simple-target, See ede-proj-target, See project-am-target.

Slots:
:name

Type: string

Name of this target.

:path

Type: string

The path to the sources of this target. Relative to the path of the project it belongs to.

:source

Type: list
Default Value: nil

Source files in this target.

:versionsource

Type: list
Default Value: nil

Source files with a version string in them. These files are checked for a version string whenever the EDE version of the master project is changed. When strings are found, the version previously there is updated.

8.8.1.1 Specialized Methods

Method: ede-preprocessor-map :AFTER this

Get the pre-processor map for project THIS.

Method: eieio-speedbar-description :AFTER obj

Provide a speedbar description for OBJ.

Method: project-compile-target :AFTER obj &optional command

Compile the current target OBJ. Argument COMMAND is the command to use for compiling the target.

Method: project-debug-target :AFTER obj

Run the current project target OBJ in a debugger.

Method: ede-convert-path :AFTER this path

Convert path in a standard way for a given project. Default to making it project relative. Argument THIS is the project to convert PATH to.

Method: ede-name :AFTER this

Return the name of THIS target.

Method: ede-target-buffer-in-sourcelist :AFTER this buffer source

Return non-nil if object THIS is in BUFFER to a SOURCE list. Handles complex path issues.

Method: eieio-speedbar-derive-line-path :AFTER obj &optional depth

Return the path to OBJ. Optional DEPTH is the depth we start at.

Method: ede-buffer-header-file :AFTER this buffer

There are no default header files in EDE. Do a quick check to see if there is a Header tag in this buffer.

Method: project-remove-file :AFTER ot fnnd

Remove the current buffer from project target OT. Argument FNND is an argument.

Method: ede-buffer-documentation-files :AFTER this buffer

Check for some documentation files for THIS. Also do a quick check to see if there is a Documentation tag in this BUFFER.

Method: ede-map-target-buffers :AFTER this proc

For THIS, execute PROC on all buffers belonging to THIS.

Method: eieio-speedbar-child-description :AFTER obj

Provide a speedbar description for a plain-child of OBJ. A plain child is a child element which is not an EIEIO object.

Method: ede-object-keybindings :BEFORE this

Retrieves the slot keybindings from an object of class ede-target

Method: ede-description :AFTER this

Return a description suitable for the minibuffer about THIS.

Method: eieio-speedbar-object-children :AFTER this

Return the list of speedbar display children for THIS.

Method: ede-system-include-path :AFTER this

Get the system include path used by project THIS.

Method: ede-object-sourcecode :BEFORE this

Retrieves the slot sourcetype from an object of class ede-target

Method: ede-expand-filename :AFTER this filename &optional force

Return a fully qualified file name based on target THIS. FILENAME should be a filename which occurs in a directory in which THIS works. Optional argument FORCE forces the default filename to be provided even if it doesn’t exist.

Method: ede-menu-items-build :AFTER obj &optional current

Return a list of menu items for building target OBJ. If optional argument CURRENT is non-nil, return sub-menu code.

Method: ede-want-file-p :AFTER this file

Return non-nil if THIS target wants FILE.

Method: ede-update-version-in-source :AFTER this version

In sources for THIS, change version numbers to VERSION.

Method: project-delete-target :AFTER ot

Delete the current target OT from its parent project.

Method: ede-target-sourcecode :AFTER this

Return the sourcecode objects which THIS permits.

Method: eieio-speedbar-child-make-tag-lines :AFTER this depth

Create a speedbar tag line for a child of THIS. It has depth DEPTH.

Method: eieio-speedbar-object-buttonname :AFTER object

Return a string to use as a speedbar button for OBJECT.

Method: eieio-done-customizing :AFTER target

Call this when a user finishes customizing TARGET.

Method: project-edit-file-target :AFTER ot

Edit the target OT associated with this file.

Method: ede-documentation :AFTER this

Return a list of files that provides documentation. Documentation is not for object THIS, but is provided by THIS for other files in the project.

Method: ede-want-file-source-p :AFTER this file

Return non-nil if THIS target wants FILE.

Method: ede-want-file-auxiliary-p :AFTER this file

Return non-nil if THIS target wants FILE.

Method: project-add-file :AFTER ot file

Add the current buffer into project target OT. Argument FILE is the file to add.

Method: ede-target-name :AFTER this

Return the name of THIS target, suitable for make or debug style commands.

Method: ede-object-menu :BEFORE this

Retrieves the slot menu from an object of class ede-target

Next: , Previous: , Up: Targets   [Contents]

8.8.2 ede-proj-target

Inheritance Tree:
eieio-speedbar
eieio-speedbar-directory-button
ede-target

See ede-target.

ede-proj-target
Children:

See ede-proj-target-makefile, ede-proj-target-aux, See ede-proj-target-scheme.

Slots:
:name

Type: string

Name of this target.

:path

Type: string

The path to the sources of this target. Relative to the path of the project it belongs to.

:auxsource

Type: list
Default Value: nil

Auxiliary source files included in this target. Each of these is considered equivalent to a source file, but it is not distributed, and each should have a corresponding rule to build it.

:compiler

Type: (or null symbol)
Default Value: nil

The compiler to be used to compile this object. This should be a symbol, which contains the object defining the compiler. This enables save/restore to do so by name, permitting the sharing of these compiler resources, and global customization thereof.

:linker

Type: (or null symbol)
Default Value: nil

The linker to be used to link compiled sources for this object. This should be a symbol, which contains the object defining the linker. This enables save/restore to do so by name, permitting the sharing of these linker resources, and global customization thereof.

8.8.2.1 Specialized Methods

Method: project-compile-target :AFTER obj &optional command

Compile the current target OBJ. Argument COMMAND is the command to use for compiling the target.

Method: project-debug-target :AFTER obj

Run the current project target OBJ in a debugger.

Method: ede-proj-configure-add-missing :AFTER this

Query if any files needed by THIS provided by automake are missing. Results in –add-missing being passed to automake.

Method: ede-proj-flush-autoconf :AFTER this

Flush the configure file (current buffer) to accommodate THIS. By flushing, remove any cruft that may be in the file. Subsequent calls to ede-proj-tweak-autoconf can restore items removed by flush.

Method: ede-proj-makefile-insert-rules :AFTER this

Insert rules needed by THIS target.

Method: project-remove-file :AFTER target file

For TARGET, remove FILE. FILE must be massaged by ede-convert-path.

Method: ede-proj-configure-create-missing :AFTER this

Add any missing files for THIS by creating them.

Method: ede-proj-makefile-sourcevar :AFTER this

Return the variable name for THIS’s sources.

Method: ede-proj-makefile-insert-variables :AFTER this &optional moresource

Insert variables needed by target THIS. Optional argument MORESOURCE is a list of additional sources to add to the sources variable.

Method: ede-proj-makefile-insert-automake-post-variables :AFTER this

Insert variables needed by target THIS in Makefile.am after SOURCES.

Method: ede-proj-makefile-insert-dist-dependencies :AFTER this

Insert any symbols that the DIST rule should depend on. Argument THIS is the target that should insert stuff.

Method: ede-proj-linkers :AFTER obj

List of linkers being used by OBJ. If the linker slot is empty, concoct one on a first match found basis for any given type from the availablelinkers slot. Otherwise, return the linker slot. Converts all symbols into the objects to be used.

Method: ede-proj-makefile-garbage-patterns :AFTER this

Return a list of patterns that are considered garbage to THIS. These are removed with make clean.

Method: ede-proj-tweak-autoconf :AFTER this

Tweak the configure file (current buffer) to accommodate THIS.

Method: ede-proj-compilers :AFTER obj

List of compilers being used by OBJ. If the compiler slot is empty, concoct one on a first match found basis for any given type from the availablecompilers slot. Otherwise, return the compiler slot. Converts all symbols into the objects to be used.

Method: project-delete-target :AFTER this

Delete the current target THIS from its parent project.

Method: ede-proj-makefile-target-name :AFTER this

Return the name of the main target for THIS target.

Method: eieio-done-customizing :AFTER target

Call this when a user finishes customizing this object. Argument TARGET is the project we are completing customization on.

Method: ede-proj-makefile-insert-user-rules :AFTER this

Insert user specified rules needed by THIS target.

Method: project-add-file :AFTER this file

Add to target THIS the current buffer represented as FILE.

Method: ede-proj-makefile-insert-automake-pre-variables :AFTER this

Insert variables needed by target THIS in Makefile.am before SOURCES.

Method: ede-proj-makefile-insert-dist-filepatterns :AFTER this

Insert any symbols that the DIST rule should depend on. Argument THIS is the target that should insert stuff.

Method: ede-proj-makefile-dependency-files :AFTER this

Return a list of source files to convert to dependencies. Argument THIS is the target to get sources from.

Method: ede-proj-makefile-insert-source-variables :AFTER this &optional moresource

Insert the source variables needed by THIS. Optional argument MORESOURCE is a list of additional sources to add to the sources variable.

Next: , Previous: , Up: Targets   [Contents]

8.8.3 ede-proj-target-makefile

Inheritance Tree:
eieio-speedbar
eieio-speedbar-directory-button
ede-target

See ede-target.

ede-proj-target

See ede-proj-target.

ede-proj-target-makefile
Children:

See semantic-ede-proj-target-grammar, See ede-proj-target-makefile-objectcode, See ede-proj-target-elisp, See ede-proj-target-makefile-miscelaneous, See ede-proj-target-makefile-info.

Slots:
:makefile

Type: string
Default Value: "Makefile"

File name of generated Makefile.

:partofall

Type: boolean
Default Value: t

Non-nil means the rule created is part of the all target. Setting this to nil creates the rule to build this item, but does not include it in the all: rule.

:configuration-variables

Type: list
Default Value: nil

Makefile variables appended to use in different configurations. These variables are used in the makefile when a configuration becomes active. Target variables are always renamed such as foo_CFLAGS, then included into commands where the variable would usually appear.

:rules

Type: list
Default Value: nil

Arbitrary rules and dependencies needed to make this target. It is safe to leave this blank.

8.8.3.1 Specialized Methods

Method: ede-proj-makefile-dependencies :AFTER this

Return a string representing the dependencies for THIS. Some compilers only use the first element in the dependencies, others have a list of intermediates (object files), and others don’t care. This allows customization of how these elements appear.

Method: project-compile-target :AFTER obj &optional command

Compile the current target program OBJ. Optional argument COMMAND is the s the alternate command to use.

Method: ede-proj-makefile-insert-rules :AFTER this

Insert rules needed by THIS target.

Method: ede-proj-makefile-insert-variables :AFTER this &optional moresource

Insert variables needed by target THIS. Optional argument MORESOURCE is a list of additional sources to add to the sources variable.

Method: ede-proj-makefile-insert-commands :AFTER this

Insert the commands needed by target THIS. For targets, insert the commands needed by the chosen compiler.

Method: ede-proj-makefile-configuration-variables :AFTER this configuration

Return a list of configuration variables from THIS. Use CONFIGURATION as the current configuration to query.

Next: , Previous: , Up: Targets   [Contents]

8.8.4 semantic-ede-proj-target-grammar

Inheritance Tree:
eieio-speedbar
eieio-speedbar-directory-button
ede-target

See ede-target.

ede-proj-target

See ede-proj-target.

ede-proj-target-makefile

See ede-proj-target-makefile.

semantic-ede-proj-target-grammar

No children

8.8.4.1 Specialized Methods

Method: project-compile-target :AFTER obj

Compile all sources in a Lisp target OBJ.

Method: ede-proj-makefile-insert-rules :AFTER this

Insert rules needed by THIS target.

Method: ede-buffer-mine :AFTER this buffer

Return t if object THIS lays claim to the file in BUFFER. Lays claim to all -by.el, and -wy.el files.

Method: ede-proj-makefile-sourcevar :AFTER this

Return the variable name for THIS’s sources.

Method: ede-proj-makefile-insert-dist-dependencies :AFTER this

Insert dist dependencies, or intermediate targets. This makes sure that all grammar lisp files are created before the dist runs, so they are always up to date. Argument THIS is the target that should insert stuff.

Next: , Previous: , Up: Targets   [Contents]

8.8.5 ede-proj-target-makefile-objectcode

Inheritance Tree:
eieio-speedbar
eieio-speedbar-directory-button
ede-target

See ede-target.

ede-proj-target

See ede-proj-target.

ede-proj-target-makefile

See ede-proj-target-makefile.

ede-proj-target-makefile-objectcode
Children:

See ede-proj-target-makefile-archive, See ede-proj-target-makefile-program.

Slots:
:configuration-variables

Type: list
Default Value: ("debug" ("CFLAGS" . "-g") ("LDFLAGS" . "-g"))

See ede-proj-target-makefile.

8.8.5.1 Specialized Methods

Method: ede-buffer-header-file :AFTER this buffer

There are no default header files.

Method: ede-proj-makefile-sourcevar :AFTER this

Return the variable name for THIS’s sources.

Method: ede-proj-makefile-insert-variables :AFTER this &optional moresource

Insert variables needed by target THIS. Optional argument MORESOURCE is not used.

Method: ede-proj-makefile-dependency-files :AFTER this

Return a list of source files to convert to dependencies. Argument THIS is the target to get sources from.

Next: , Previous: , Up: Targets   [Contents]

8.8.6 ede-proj-target-makefile-archive

Inheritance Tree:
eieio-speedbar
eieio-speedbar-directory-button
ede-target

See ede-target.

ede-proj-target

See ede-proj-target.

ede-proj-target-makefile

See ede-proj-target-makefile.

ede-proj-target-makefile-objectcode

See ede-proj-target-makefile-objectcode.

ede-proj-target-makefile-archive

No children

8.8.6.1 Specialized Methods

Method: ede-proj-makefile-insert-rules :AFTER this

Create the make rule needed to create an archive for THIS.

Method: ede-proj-makefile-insert-source-variables :PRIMARY this

Insert bin_PROGRAMS variables needed by target THIS. We aren’t actually inserting SOURCE details, but this is used by the Makefile.am generator, so use it to add this important bin program.

Next: , Previous: , Up: Targets   [Contents]

8.8.7 ede-proj-target-makefile-program

Inheritance Tree:
eieio-speedbar
eieio-speedbar-directory-button
ede-target

See ede-target.

ede-proj-target

See ede-proj-target.

ede-proj-target-makefile

See ede-proj-target-makefile.

ede-proj-target-makefile-objectcode

See ede-proj-target-makefile-objectcode.

ede-proj-target-makefile-program
Children:

See ede-proj-target-makefile-shared-object.

Slots:
:ldlibs

Type: list
Default Value: nil

Libraries, such as "m" or "Xt" which this program depends on. The linker flag "-l" is automatically prepended. Do not include a "lib" prefix, or a ".so" suffix.

Note: Currently only used for Automake projects.

:ldflags

Type: list
Default Value: nil

Additional flags to add when linking this target. Use ldlibs to add addition libraries. Use this to specify specific options to the linker.

Note: Not currently used. This bug needs to be fixed.

8.8.7.1 Specialized Methods

Method: project-debug-target :AFTER obj

Debug a program target OBJ.

Method: ede-proj-makefile-insert-rules :AFTER this

Insert rules needed by THIS target.

Method: ede-proj-makefile-insert-automake-post-variables :AFTER this

Insert bin_PROGRAMS variables needed by target THIS.

Method: ede-proj-makefile-insert-automake-pre-variables :AFTER this

Insert bin_PROGRAMS variables needed by target THIS.

Next: , Previous: , Up: Targets   [Contents]

8.8.8 ede-proj-target-makefile-shared-object

Inheritance Tree:
eieio-speedbar
eieio-speedbar-directory-button
ede-target

See ede-target.

ede-proj-target

See ede-proj-target.

ede-proj-target-makefile

See ede-proj-target-makefile.

ede-proj-target-makefile-objectcode

See ede-proj-target-makefile-objectcode.

ede-proj-target-makefile-program

See ede-proj-target-makefile-program.

ede-proj-target-makefile-shared-object

No children

8.8.8.1 Specialized Methods

Method: ede-proj-configure-add-missing :AFTER this

Query if any files needed by THIS provided by automake are missing. Results in –add-missing being passed to automake.

Method: ede-proj-makefile-sourcevar :AFTER this

Return the variable name for THIS’s sources.

Method: ede-proj-makefile-insert-automake-post-variables :AFTER this

Insert bin_PROGRAMS variables needed by target THIS. We need to override -program which has an LDADD element.

Method: ede-proj-makefile-target-name :AFTER this

Return the name of the main target for THIS target.

Method: ede-proj-makefile-insert-automake-pre-variables :AFTER this

Insert bin_PROGRAMS variables needed by target THIS. We aren’t actually inserting SOURCE details, but this is used by the Makefile.am generator, so use it to add this important bin program.

Next: , Previous: , Up: Targets   [Contents]

8.8.9 ede-proj-target-elisp

Inheritance Tree:
eieio-speedbar
eieio-speedbar-directory-button
ede-target

See ede-target.

ede-proj-target

See ede-proj-target.

ede-proj-target-makefile

See ede-proj-target-makefile.

ede-proj-target-elisp
Children:

See ede-proj-target-elisp-autoloads.

Slots:
:aux-packages

Type: list
Default Value: nil

Additional packages needed. There should only be one toplevel package per auxiliary tool needed. These packages location is found, and added to the compile time load path.

8.8.9.1 Specialized Methods

Method: project-compile-target :AFTER obj

Compile all sources in a Lisp target OBJ. Bonus: Return a cons cell: (COMPILED . UPTODATE).

Method: ede-proj-flush-autoconf :AFTER this

Flush the configure file (current buffer) to accommodate THIS.

Method: ede-buffer-mine :AFTER this buffer

Return t if object THIS lays claim to the file in BUFFER. Lays claim to all .elc files that match .el files in this target.

Method: ede-proj-makefile-sourcevar :AFTER this

Return the variable name for THIS’s sources.

Method: ede-proj-tweak-autoconf :AFTER this

Tweak the configure file (current buffer) to accommodate THIS.

Method: ede-update-version-in-source :AFTER this version

In a Lisp file, updated a version string for THIS to VERSION. There are standards in Elisp files specifying how the version string is found, such as a -version variable, or the standard header.

Next: , Previous: , Up: Targets   [Contents]

8.8.10 ede-proj-target-elisp-autoloads

Inheritance Tree:
eieio-speedbar
eieio-speedbar-directory-button
ede-target

See ede-target.

ede-proj-target

See ede-proj-target.

ede-proj-target-makefile

See ede-proj-target-makefile.

ede-proj-target-elisp

See ede-proj-target-elisp.

ede-proj-target-elisp-autoloads

No children

Slots:
:aux-packages

Type: list
Default Value: ("cedet-autogen")

See ede-proj-target-elisp.

:autoload-file

Type: string
Default Value: "loaddefs.el"

The file that autoload definitions are placed in. There should be one load defs file for a given package. The load defs are created for all Emacs Lisp sources that exist in the directory of the created target.

:autoload-dirs

Type: list
Default Value: nil

The directories to scan for autoload definitions. If nil defaults to the current directory.

8.8.10.1 Specialized Methods

Method: ede-proj-makefile-dependencies :AFTER this

Return a string representing the dependencies for THIS. Always return an empty string for an autoloads generator.

Method: project-compile-target :AFTER obj

Create or update the autoload target.

Method: ede-proj-flush-autoconf :AFTER this

Flush the configure file (current buffer) to accommodate THIS.

Method: ede-buffer-mine :AFTER this buffer

Return t if object THIS lays claim to the file in BUFFER. Lays claim to all .elc files that match .el files in this target.

Method: ede-proj-makefile-sourcevar :AFTER this

Return the variable name for THIS’s sources.

Method: ede-proj-makefile-insert-dist-dependencies :AFTER this

Insert any symbols that the DIST rule should depend on. Emacs Lisp autoload files ship the generated .el files. Argument THIS is the target which needs to insert an info file.

Method: ede-proj-tweak-autoconf :AFTER this

Tweak the configure file (current buffer) to accommodate THIS.

Method: ede-update-version-in-source :AFTER this version

In a Lisp file, updated a version string for THIS to VERSION. There are standards in Elisp files specifying how the version string is found, such as a -version variable, or the standard header.

Method: ede-proj-compilers :AFTER obj

List of compilers being used by OBJ. If the compiler slot is empty, get the car of the compilers list.

Method: ede-proj-makefile-insert-dist-filepatterns :AFTER this

Insert any symbols that the DIST rule should distribute. Emacs Lisp autoload files ship the generated .el files. Argument THIS is the target which needs to insert an info file.

Method: ede-proj-makefile-insert-source-variables :AFTER this &optional moresource

Insert the source variables needed by THIS. Optional argument MORESOURCE is a list of additional sources to add to the sources variable.

Next: , Previous: , Up: Targets   [Contents]

8.8.11 ede-proj-target-makefile-miscelaneous

Inheritance Tree:
eieio-speedbar
eieio-speedbar-directory-button
ede-target

See ede-target.

ede-proj-target

See ede-proj-target.

ede-proj-target-makefile

See ede-proj-target-makefile.

ede-proj-target-makefile-miscelaneous

No children

Slots:
:submakefile

Type: string
Default Value: ""

Miscellaneous sources which have a specialized makefile. The sub-makefile is used to build this target.

8.8.11.1 Specialized Methods

Method: ede-proj-makefile-insert-rules :AFTER this

Create the make rule needed to create an archive for THIS.

Method: ede-proj-makefile-sourcevar :AFTER this

Return the variable name for THIS’s sources.

Method: ede-proj-makefile-dependency-files :AFTER this

Return a list of files which THIS target depends on.

Next: , Previous: , Up: Targets   [Contents]

8.8.12 ede-proj-target-makefile-info

Inheritance Tree:
eieio-speedbar
eieio-speedbar-directory-button
ede-target

See ede-target.

ede-proj-target

See ede-proj-target.

ede-proj-target-makefile

See ede-proj-target-makefile.

ede-proj-target-makefile-info

No children

Slots:
:mainmenu

Type: string
Default Value: ""

The main menu resides in this file. All other sources should be included independently.

8.8.12.1 Specialized Methods

Method: ede-proj-configure-add-missing :AFTER this

Query if any files needed by THIS provided by automake are missing. Results in –add-missing being passed to automake.

Method: object-write :AFTER this

Before committing any change to THIS, make sure the mainmenu is first.

Method: ede-proj-makefile-sourcevar :AFTER this

Return the variable name for THIS’s sources.

Method: ede-proj-makefile-insert-dist-dependencies :AFTER this

Insert any symbols that the DIST rule should depend on. Texinfo files want to insert generated .info files. Argument THIS is the target which needs to insert an info file.

Method: ede-proj-makefile-target-name :AFTER this

Return the name of the main target for THIS target.

Method: ede-documentation :AFTER this

Return a list of files that provides documentation. Documentation is not for object THIS, but is provided by THIS for other files in the project.

Method: ede-proj-makefile-insert-dist-filepatterns :AFTER this

Insert any symbols that the DIST rule should depend on. Texinfo files want to insert generated .info files. Argument THIS is the target which needs to insert an info file.

Method: ede-proj-makefile-insert-source-variables :AFTER this &optional moresource

Insert the source variables needed by THIS info target. Optional argument MORESOURCE is a list of additional sources to add to the sources variable. Does the usual for Makefile mode, but splits source into two variables when working in Automake mode.

Next: , Previous: , Up: Targets   [Contents]

8.8.13 ede-proj-target-scheme

Inheritance Tree:
eieio-speedbar
eieio-speedbar-directory-button
ede-target

See ede-target.

ede-proj-target

See ede-proj-target.

ede-proj-target-scheme

No children

Slots:
:interpreter

Type: string
Default Value: "guile"

The preferred interpreter for this code.

8.8.13.1 Specialized Methods

Method: ede-proj-tweak-autoconf :AFTER this

Tweak the configure file (current buffer) to accommodate THIS.

Next: , Previous: , Up: Targets   [Contents]

8.8.14 project-am-target

Inheritance Tree:
eieio-speedbar
eieio-speedbar-directory-button
ede-target

See ede-target.

project-am-target
Children:

See project-am-objectcode, project-am-header, See project-am-lisp, See project-am-texinfo, See project-am-man.

8.8.14.1 Specialized Methods

Method: project-compile-target-command :AFTER this

Default target to use when compiling a given target.

Method: project-make-dist :AFTER this

Run the current project in the debugger.

Method: project-edit-file-target :AFTER obj

Edit the target associated with this file.

Next: , Previous: , Up: Targets   [Contents]

8.8.15 project-am-objectcode

Inheritance Tree:
eieio-speedbar
eieio-speedbar-directory-button
ede-target

See ede-target.

project-am-target

See project-am-target.

project-am-objectcode
Children:

See project-am-program, project-am-lib.

8.8.15.1 Specialized Methods

Method: project-am-macro :AFTER this

Return the default macro to ’edit’ for this object type.

Method: project-debug-target :AFTER obj

Run the current project target in a debugger.

Method: project-compile-target-command :AFTER this

Default target to use when compiling an object code target.

Method: ede-buffer-header-file :AFTER this buffer

There are no default header files.

Next: , Previous: , Up: Targets   [Contents]

8.8.16 project-am-program

Inheritance Tree:
eieio-speedbar
eieio-speedbar-directory-button
ede-target

See ede-target.

project-am-target

See project-am-target.

project-am-objectcode

See project-am-objectcode.

project-am-program

No children

Slots:
:ldadd

Default Value: nil

Additional LD args.

Next: , Previous: , Up: Targets   [Contents]

8.8.17 project-am-header-noinst

Inheritance Tree:
eieio-speedbar
eieio-speedbar-directory-button
ede-target

See ede-target.

project-am-target

See project-am-target.

project-am-header.
project-am-header-noinst

No children

8.8.17.1 Specialized Methods

Method: project-am-macro :AFTER this

Return the default macro to ’edit’ for this object.

Next: , Previous: , Up: Targets   [Contents]

8.8.18 project-am-header-inst

Inheritance Tree:
eieio-speedbar
eieio-speedbar-directory-button
ede-target

See ede-target.

project-am-target

See project-am-target.

project-am-header.
project-am-header-inst

No children

8.8.18.1 Specialized Methods

Method: project-am-macro :AFTER this

Return the default macro to ’edit’ for this object.

Next: , Previous: , Up: Targets   [Contents]

8.8.19 project-am-lisp

Inheritance Tree:
eieio-speedbar
eieio-speedbar-directory-button
ede-target

See ede-target.

project-am-target

See project-am-target.

project-am-lisp

No children

8.8.19.1 Specialized Methods

Method: project-am-macro :AFTER this

Return the default macro to ’edit’ for this object.

Next: , Previous: , Up: Targets   [Contents]

8.8.20 project-am-texinfo

Inheritance Tree:
eieio-speedbar
eieio-speedbar-directory-button
ede-target

See ede-target.

project-am-target

See project-am-target.

project-am-texinfo

No children

Slots:
:include

Default Value: nil

Additional texinfo included in this one.

8.8.20.1 Specialized Methods

Method: project-am-macro :AFTER this

Return the default macro to ’edit’ for this object type.

Method: project-compile-target-command :AFTER this

Default target to use when compiling a texinfo file.

Method: ede-documentation :AFTER this

Return a list of files that provides documentation. Documentation is not for object THIS, but is provided by THIS for other files in the project.

Previous: , Up: Targets   [Contents]

8.8.21 project-am-man

Inheritance Tree:
eieio-speedbar
eieio-speedbar-directory-button
ede-target

See ede-target.

project-am-target

See project-am-target.

project-am-man

No children

8.8.21.1 Specialized Methods

Method: project-am-macro :AFTER this

Return the default macro to ’edit’ for this object type.

Next: , Previous: , Up: Extending EDE   [Contents]

8.9 Sourcecode

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

Up: Sourcecode   [Contents]

8.9.1 ede-sourcecode

Inheritance Tree:
eieio-instance-inheritor
ede-sourcecode

No children

Slots:
:parent-instance

Type: eieio-instance-inheritor-child

The parent of this instance. If a slot of this class is reference, and is unbound, then the parent is checked for a value.

:name

Type: string

The name of this type of source code. Such as "C" or "Emacs Lisp"

:sourcepattern

Type: string
Default Value: ".*"

Emacs regex matching sourcecode this target accepts.

:auxsourcepattern

Type: (or null string)
Default Value: nil

Emacs regex matching auxiliary source code this target accepts. Aux source are source code files needed for compilation, which are not compiled themselves.

:enable-subdirectories

Type: boolean
Default Value: nil

Non-nil if this sourcecode type uses subdirectores. If sourcecode always lives near the target creating it, this should be nil. If sourcecode can, or typically lives in a subdirectory of the owning target, set this to t.

:garbagepattern

Type: list
Default Value: nil

Shell file regex matching files considered as garbage. This is a list of items added to an rm command when executing a clean type directive.

8.9.1.1 Specialized Methods

Method: ede-want-any-files-p :AFTER this filenames

Return non-nil if THIS will accept any files in FILENAMES.

Method: ede-want-any-source-files-p :AFTER this filenames

Return non-nil if THIS will accept any source files in FILENAMES.

Method: ede-want-any-auxiliary-files-p :AFTER this filenames

Return non-nil if THIS will accept any aux files in FILENAMES.

Method: ede-buffer-header-file :AFTER this filename

Return a list of file names of header files for THIS with FILENAME. Used to guess header files, but uses the auxsource regular expression.

Method: ede-want-file-p :AFTER this filename

Return non-nil if sourcecode definition THIS will take FILENAME.

Method: ede-want-file-source-p :AFTER this filename

Return non-nil if THIS will take FILENAME as an auxiliary .

Method: ede-want-file-auxiliary-p :AFTER this filename

Return non-nil if THIS will take FILENAME as an auxiliary .

Previous: , Up: Extending EDE   [Contents]

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

Next: , Up: Compilers   [Contents]

8.10.1 ede-compilation-program

Inheritance Tree:
eieio-instance-inheritor
ede-compilation-program
Children:

See ede-compiler, See ede-linker.

Slots:
:parent-instance

Type: eieio-instance-inheritor-child

The parent of this instance. If a slot of this class is reference, and is unbound, then the parent is checked for a value.

:name

Type: string

Name of this type of compiler.

:variables

Type: list

Variables needed in the Makefile for this compiler. An assoc list where each element is (VARNAME . VALUE) where VARNAME is a string, and VALUE is either a string, or a list of strings. For example, GCC would define CC=gcc, and emacs would define EMACS=emacs.

:sourcetype

Type: list

A list of ede-sourcecode See ede-sourcecode. objects this class will handle. This is used to match target objects with the compilers and linkers they can use, and which files this object is interested in.

:rules

Type: list
Default Value: nil

Auxiliary rules needed for this compiler to run. For example, yacc/lex files need additional chain rules, or inferences.

:commands

Type: list

The commands used to execute this compiler. The object which uses this compiler will place these commands after its rule definition.

:autoconf

Type: list
Default Value: nil

Autoconf function to call if this type of compiler is used. When a project is in Automake mode, this defines the autoconf function to call to initialize automake to use this compiler. For example, there may be multiple C compilers, but they all probably use the same autoconf form.

:objectextention

Type: string

A string which is the extension used for object files. For example, C code uses .o on unix, and Emacs Lisp uses .elc.

8.10.1.1 Specialized Methods

Method: ede-proj-flush-autoconf :AFTER this

Flush the configure file (current buffer) to accommodate THIS.

Method: ede-proj-makefile-insert-rules :AFTER this

Insert rules needed for THIS compiler object.

Method: ede-proj-makefile-insert-variables :AFTER this

Insert variables needed by the compiler THIS.

Method: ede-proj-makefile-insert-commands :AFTER this

Insert the commands needed to use compiler THIS. The object creating makefile rules must call this method for the compiler it decides to use after inserting in the rule.

Method: ede-object-sourcecode :AFTER this

Retrieves the slot sourcetype from an object of class ede-compilation-program

Method: ede-proj-tweak-autoconf :AFTER this

Tweak the configure file (current buffer) to accommodate THIS.

Next: , Previous: , Up: Compilers   [Contents]

8.10.2 ede-compiler

Inheritance Tree:
eieio-instance-inheritor
ede-compilation-program

See ede-compilation-program.

ede-compiler
Children:

See ede-object-compiler, semantic-ede-grammar-compiler-class.

Create a new object with name NAME of class type ede-compiler

Slots:
:parent-instance

Type: eieio-instance-inheritor-child

The parent of this instance. If a slot of this class is reference, and is unbound, then the parent is checked for a value.

:name

Type: string

Name of this type of compiler.

:variables

Type: list

Variables needed in the Makefile for this compiler. An assoc list where each element is (VARNAME . VALUE) where VARNAME is a string, and VALUE is either a string, or a list of strings. For example, GCC would define CC=gcc, and emacs would define EMACS=emacs.

:sourcetype

Type: list

A list of ede-sourcecode See ede-sourcecode. objects this class will handle. This is used to match target objects with the compilers and linkers they can use, and which files this object is interested in.

:commands

Type: list

The commands used to execute this compiler. The object which uses this compiler will place these commands after its rule definition.

:objectextention

Type: string

A string which is the extension used for object files. For example, C code uses .o on unix, and Emacs Lisp uses .elc.

:makedepends

Type: boolean
Default Value: nil

Non-nil if this compiler can make dependencies.

:uselinker

Type: boolean
Default Value: nil

Non-nil if this compiler creates code that can be linked. This requires that the containing target also define a list of available linkers that can be used.

8.10.2.1 Specialized Methods

Method: ede-proj-makefile-insert-object-variables :AFTER this targetname sourcefiles

Insert an OBJ variable to specify object code to be generated for THIS. The name of the target is TARGETNAME as a string. SOURCEFILES is the list of files to be objectified. Not all compilers do this.

Method: ede-compiler-intermediate-objects-p :AFTER this

Return non-nil if THIS has intermediate object files. If this compiler creates code that can be linked together, then the object files created by the compiler are considered intermediate.

Method: ede-compiler-intermediate-object-variable :AFTER this targetname

Return a string based on THIS representing a make object variable. TARGETNAME is the name of the target that these objects belong to.

Next: , Previous: , Up: Compilers   [Contents]

8.10.3 ede-object-compiler

Inheritance Tree:
eieio-instance-inheritor
ede-compilation-program

See ede-compilation-program.

ede-compiler

See ede-compiler.

ede-object-compiler

No children

Slots:
:uselinker

Type: boolean
Default Value: t

See ede-compiler.

:dependencyvar

Type: list

A variable dedicated to dependency generation.

8.10.3.1 Specialized Methods

Method: ede-proj-makefile-insert-variables :AFTER this

Insert variables needed by the compiler THIS.

Previous: , Up: Compilers   [Contents]

8.10.4 ede-linker

Inheritance Tree:
eieio-instance-inheritor
ede-compilation-program

See ede-compilation-program.

ede-linker

No children

Create a new object with name NAME of class type ede-linker

Slots:
:name

Type: string

Name of this type of compiler.

:variables

Type: list

Variables needed in the Makefile for this compiler. An assoc list where each element is (VARNAME . VALUE) where VARNAME is a string, and VALUE is either a string, or a list of strings. For example, GCC would define CC=gcc, and emacs would define EMACS=emacs.

:sourcetype

Type: list

A list of ede-sourcecode See ede-sourcecode. objects this class will handle. This is used to match target objects with the compilers and linkers they can use, and which files this object is interested in.

:commands

Type: list

The commands used to execute this compiler. The object which uses this compiler will place these commands after its rule definition.

:objectextention

Type: string

A string which is the extension used for object files. For example, C code uses .o on unix, and Emacs Lisp uses .elc.

Previous: , Up: EDE   [Contents]

Appendix A GNU Free Documentation License

Version 1.3, 3 November 2008 
Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
https://fsf.org/

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
  1. PREAMBLE

    The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

    This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

    We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

  2. APPLICABILITY AND DEFINITIONS

    This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.

    A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

    A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

    The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.

    The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

    A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.

    Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.

    The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.

    The “publisher” means any person or entity that distributes copies of the Document to the public.

    A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.

    The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.

  3. VERBATIM COPYING

    You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

    You may also lend copies, under the same conditions stated above, and you may publicly display copies.

  4. COPYING IN QUANTITY

    If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

    If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

    If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

    It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

  5. MODIFICATIONS

    You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

    1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
    2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.
    3. State on the Title page the name of the publisher of the Modified Version, as the publisher.
    4. Preserve all the copyright notices of the Document.
    5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
    6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
    7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document’s license notice.
    8. Include an unaltered copy of this License.
    9. Preserve the section Entitled “History”, Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled “History” in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
    10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the “History” section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
    11. For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
    12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
    13. Delete any section Entitled “Endorsements”. Such a section may not be included in the Modified Version.
    14. Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title with any Invariant Section.
    15. Preserve any Warranty Disclaimers.

    If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles.

    You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

    You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

    The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

  6. COMBINING DOCUMENTS

    You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.

    The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

    In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.”

  7. COLLECTIONS OF DOCUMENTS

    You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

    You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

  8. AGGREGATION WITH INDEPENDENT WORKS

    A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.

    If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.

  9. TRANSLATION

    Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.

    If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.

  10. TERMINATION

    You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License.

    However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.

    Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.

    Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it.

  11. FUTURE REVISIONS OF THIS LICENSE

    The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See https://www.gnu.org/licenses/.

    Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Document.

  12. RELICENSING

    “Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A “Massive Multiauthor Collaboration” (or “MMC”) contained in the site means any set of copyrightable works thus published on the MMC site.

    “CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization.

    “Incorporate” means to publish or republish a Document, in whole or in part, as part of another Document.

    An MMC is “eligible for relicensing” if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008.

    The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing.

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page: 

  Copyright (C)  year  your name.
  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, no Front-Cover Texts, and no Back-Cover
  Texts.  A copy of the license is included in the section entitled ``GNU
  Free Documentation License''.

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with…Texts.” line with this: 

    with the Invariant Sections being list their titles, with
    the Front-Cover Texts being list, and with the Back-Cover Texts
    being list.

If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.