Installation and first steps of ECB

This section describes how to install ECB and setup Emacs correctly and what are the first steps after activation of ECB

Installation

Requirements

This section describes the requirements of ECB. Just follow these steps and the requirements of ECB are fulfilled.

1. Emacs-version: ECB works only with Emacs >= 21! If you have an older one, please upgrade.
2. Deprecated: Install CEDET-suite: Get it from http://cedet.sourceforge.net, read the setup-instructions in http://cedet.sourceforge.net/setup.shtml and read also the shipped file INSTALL. Please note: ECB requires now a complete CEDET-installation! It will not longer work with outdated separate packages semantic 1.4.X, eieio 0.X and speedbar 0.X!
3. Only for XEmacs-users: If you use XEmacs you must have installed the package c-support (contains hideshow.el). If you want to read the online-help of ECB in HTML-format you must have the library browse-url (part of the mail-lib XEmacs package) installed; this package is also needed for submitting problem-reports to the ECB-maintainers!
4. Optional for Java-coding: If Java code is edited the ECB works best when the JDEE package (http://jdee.sourceforge.net) is installed.

Do not install ECB before you have successfully installed the requirements!

Installation of ECB as a XEmacs-package

Deprecated but kept for historical purposes.

This section is only relevant for XEmacs-users!

In previous versions of ECB XEmacs-users could use the package-management-system of XEmacs for first-time downloading/installing ECB or for upgrading to a newer version of ECB.

Beginning with version 2.33 ECB does no longer support the old versions of semantic, eieio and speedbar not part of the CEDET-suite. ECB >= 2.33 requires fully installed CEDET-suite with version >= 1.0pre6. This one is not available as XEmacs-package. Therefore ECB can also not be run as XEmacs-package. If cedet will become a XEmacs-package then probably ECB will come back as XEmacs-package. But in the meanwhile you have to install ECB “by hand” as described in the next section (see Standard ECB-Installation).

Standard installation of ECB for Emacs

Follow exatly these steps to install ECB:

1. Fulfill all requirements ECB needs (see Requirements) ECB performs two automated checks:

   • At load-time: It checks if cedet is at least installed so ECB can be loaded. If not it reports an error.
   • At start-time: It checks if the correct versions of cedet and semantic are installed and gives you proper feedback.

   So if you are not sure if you have installed the required packages at all or if you have installed the correct versions of these packages then do not worry about this, just go on with the following installation steps: If ECB is missing something it will give you proper feedback and support not later than at load-time or start-time!

2. Download and unpack the ECB archive (probably you have already done this :-)

3. Add the new ECB-directory to your load-path variable. You MUST add the ECB-install-directory to the load-path either by changing the load-path variable directly in your .emacs or site-lisp/site-start.el or by working with a file subdirs.el [1].

   So for example the needed entry for your .emacs-file could be:

    (add-to-list 'load-path
                 "/path/to/your/ecb/installation/directory")
   

   ATTENTION: ECB is NOT properly installed if it's directory is not added to load-path and for example just loaded by

    (load-file "/path/to/ecb/ecb.el")
   

   Do not do this! It will not work!

4. Load ECB by adding code to your .emacs: If you want to load the complete ECB at (X)Emacs-loadtime (Advantage: All ECB-options available after loading ECB. Disadvantage: Increasing lead-time [2]):

    (require 'ecb)
   

   If you want to load the ECB first after starting it by ecb-activate (Advantage: Fast loading [3]. Disadvantage: ECB- and semantic-options first available after starting ECB):

    (require 'ecb-autoloads)
   

   This loads all available autoloads of ECB, e.g. ecb-activate, ecb-minor-mode, ecb-byte-compile and ecb-show-help.

   Regardless which method you prefer: In both cases the used statement must be placed after the statement of step 3!

5. Restart Emacs. ECB is now ready for use and can be activated by calling M-x ecb-activate or ecb-minor-mode. Now you can either starting using ECB or you can do these optional installation steps:

6. Reading the online help with ecb-show-help Maybe you are interested to read the online-help of ECB before first start.

7. Bytecompiling ECB with ecb-byte-compile This byte compiles ECB. You can safely ignore all messages if there are any. (You can also bytecompile ECB from the command-line either by using the Makefile or by using the batch-file make.bat; just read the comments in that file you choose.)

8. Installing the Info-help of ECB The ECB distribution contains a subdirectory info-help which contains the online-help of ECB in Info-format. You can install this online help so it's available in the Top-directory of Info. There are two ways to do this:

   • Use “install-info” (recommended):

   1. Copy the files of the subdirectory info-help into the info-directory of Emacs

   2. Install the file info-help/ecb.info with the command “install-info” (if available on your system) in the dir-file. The supplied Makefile offers a target install-help which does both of these steps. You have just to call make install-help with the correct EMACSINFOPATH set (see the comment in Makefile). Here is an example:

        make EMACSINFOPATH=/path/to/emacs/info install-help
      

   • Manual Installation: Copy the files of the subdirectory info-help into the info-directory of Emacs and modify the file dir manually.

   But it doesn't matter if you do not execute this step (8.) because the online help of ECB is always available though, see ecb-show-help (see Interactive ECB commands).

Footnotes

[1] This works at least for Emacs but XEmacs may have slightly different mechanisms; see the XEmacs documentation

[2] Cause of full loading of ECB itself and also the packages semantic, eieio and speedbar regardless if ECB is started.

[3] ECB, semantic, eieio and speedbar are first loaded after starting ECB or with other words: ECB and semantic are not loaded if you do not use/need them

How to set up Emacs for File Parsing with ECB

NOTE: Normally it should not be necessary to bother with the following stuff unless you are having problems getting ECB working.

General Hints

ECB is for browsing files and therefore you have to setup your Emacs-configuration properly so the file-parsing engines like semantic, imenu or etags can be activated automatically for parsing your Emacs-Lisp, C, C++ or Java buffers [1]. For this Emacs must activate the correct major-mode for the source-files and Emacs can only do this if the option auto-mode-alist is setup correctly. The correct major-modes and possible file-extensions [2] are:

Language	Major-mode	Extension(s)
Emacs Lisp	emacs-lisp-mode	.el
C	c-mode	.h, .c
C++	c++-mode	.h, .hxx, .hh, .HH, .cxx, .cpp, .cc, .CC
Java	java-mode or jde-mode (if you use JDEE)	.java

Example: If you want files with extension “.cpp” being c++-parsed by semantic and ECB, your auto-mode-alist must contain an entry like:

("\\.cpp\\'" . c++-mode)

After this ECB will correctly parse your “.cpp”-sources and display all the parsing information in the ECB-methods buffer.

Footnotes

[1] semantic supports some more “languages” like Phython, Makefiles and some more. But these are the most important ones.

[2] Especially for C++ and C you can use any extension you want but these are the most common ones!

Setting up CEDET/semantic

NOTE: This section is deprecated and will be removed in the future. It is included for historical purposes. We now use CEDET/semantic included in Emacs.

To ensure ECB and semantic are working correctly for all by semantic supported languages you have to pay attention to the following aspects concerning your Emacs-setup:

1. Setting up CEDET/semantic itself

   This section implies that you have already successfully installed the CEDET-suite and describes how to setup cadet and here mainly semantic.

   For all semantic-supported file-types parsing files is done completely by semantic. ECB just displays the parsing results. For all needs of ECB semantic is completely setup by ECB itself, i.e. ECB sets up semantic for you!

   Please note: Nevertheless you should read carefully the file INSTALL shipped with the cedet-suite. In addition the CEDET-website offers a link to a “Gentle introduction to Cedet”. It's worth to read it! You find it here: http://xtalk.msk.su/~ott/en/writings/emacs-devenv/EmacsCedet.html If CEDET is not correctly installed then ECB can not setup semantic for its needs.

   Minimum setup recommendation: It is very useful to enable the global-semantic-idle-scheduler-mode and global-semanticdb-minor-mode. Read the manual of cedet/semantic how to do this. With CEDET-versions >= 1.0pre6 this can be done by adding semantic-load-enable-minimum-features to your startup-file. Please read also the subsection “Jumping to the definition of external types” in ECB Methods-window.

2. Checking your hooks

   If you have already checked point (1.) and if you have still problems getting ECB/semantic working properly for your sources you should check the related major-mode hook. Every major-mode X has a hook with name “X-hook” which is evaluated after activating the major-mode (see above, 2.), e.g. the hook for the major-mode c++-mode is c++-mode-hook.

   Semantic adds automatically during load-time a special “semantic-setup” to these major-mode hooks [1] in form of a “setup-function”. Example: For c and c++ modes semantic adds semantic-default-c-setup to c-mode-hook and c++-mode-hook.

   If your own Emacs-setup (e.g. in .emacs or site-lisp/site-start.el) overwrites such a major-mode-hook then semantic can not be activated for this major-mode and in consequence ECB can not work properly too!

   Check if your Emacs-setup uses somewhere setq for adding code to a major-mode-hook. IMPORTANT: Use add-hook instead of sets [2]!

   If your source-files are “running” with correct major-mode and correct major-mode hooks ECB and semantic will do what you expect them doing!

Footnotes

[1] Of course only for major-modes supported by semantic!

[2] setq replaces/overwrites the current value of a hook with the new value whereas add-hook adds the new value to the old-value of the hook!

Setup for file types not supported by semantic

From version 1.94 on ECB supports also parsing and displaying file-contents for file-types not supported by semantic (i.e. there is no semantic-grammar available for such file-types).

Such non-semantic file-types can often be parsed by imenu and/or etags. Both of these parsing methods are now supported: ECB can display the results of imenu and/or etags in its Method-buffer. ECB uses for this speedbar-logic. Therefore the following speedbar options takes effect for this feature:

• speedbar-dynamic-tags-function-list
• speedbar-tag-split-minimum-length
• speedbar-tag-regroup-maximum-length
• speedbar-tag-hierarchy-method

Normally there should be no need for you to bother with these options, because the default values are suitable for most situations! But if you are not satisfied with the parsing/display results then you can change some of these options.

First steps after activating ECT for the first time

This section of the ECB online-help is displayed automatically by ECB after activating ECB first time and describes what are the first basic steps:

1. Configure where ECB can find your sources:

   Call M-x customize-option RET eco-source-path RET [1]. This lets you customize the option ecb-source-path with the customize-feature of Emacs. This opens a customize-buffer where you can insert all the directories where ECB can find your source-files. Save your changes with the button “Save for future sessions” and then throw away this customize-buffer either by killing it with M-x kill-buffer or clicking at the button “Finish”.

2. Take a look at the most important options of ECB Call M-x ecb-customize-most-important RET and see a list of options which you should at least know that these options exist.

3. Read the online-help of ECB:

   The online-help of ECB is available via

   • calling M-x ecb-show-help,
   • pressing C-c . h or
   • using the menu “ECB”.

   (The section you are currently reading is part of the online-help of ECB)

   The chapter “Common use-cases” is also very interesting!

4. Start working with ECB.

Footnotes

[1] This means first hitting the keys M (Meta- or Alt-key) and x simultaneously, inserting “customize-option” in the minibuffer, hitting RETURN, inserting “ecb-source-path” in the minibuffer and finally hitting RETURN again