1. Installation and first steps of ECB

This chapter describes how to install ECB and setup (X)Emacs correctly and what are the first steps after activation of ECB.

1.1 Installation of ECB

This section describes how to install ECB.

1.1.1 Installation of ECB for XEmacs users

For XEmacs-users it is strongly recommended to use the package-management-system of XEmacs for first-time downloading/installing ECB or for upgrading to a newer version of ECB. Here is a short guide (for details about the package-manager of XEmacs see the related info-manual):

Caution: If ECB is already installed and you just want upgrading to a newer version then it is recommended to deactivate ECB before proceeding with the steps below!

1. Choose a download-site

   This can be done via the menu "Tools --> Packages --> Add Download Site": Choose one of the listed sites. Or you can customize the option package-get-remote by hand and save it for future sessions.

2. Activate the packages list

   This can be done either by the menu "Tools --> Packages --> List and Install" or via the command pui-list-packages. After that a special packages-buffer is displayed where you can interactively install or upgrade packages. At the end of this buffer there is a short description how to use this buffer.

3. Install ECB and all required packages

   Mark the package named "ecb" for install. Do this also for the required packages "semantic", "eieio" and "speedbar". The package "mail-lib" is needed for easy submitting of problem-reports to the ECB-maintainers and the package "c-support" is needed for easy using hideshow within the Methods-buffer of ECB(1).

   After marking all needed packages for installation hit x to install them.

   If you have already installed ECB and you want just upgrading to the latest available version then proceed as described above - same if you want to upgrade one of the required packages.

4. Start ECB

   Now you can immediately start ECB via the command ecb-activate; there is no need to restart XEmacs! As an alternative you can first read the online-help via ecb-show-help.

If you do not like the package-manager of XEmacs but you want installing ECB "by hand" direct from the ECB-website then you have to follow the instructions for GNU Emacs, see 1.1.2 Installation of ECB for GNU Emacs users.

1.1.2 Installation of ECB for GNU Emacs users

IMPORTANT: If you are a XEmacs-user please read 1.1.1 Installation of ECB for XEmacs users before proceeding with the following instructions!

Using the new cedet 1.0 suite: From beginning with version 2.01 ECB supports the next generation of the cedet-tools. But before the cedet 1.0 suite becomes stable this means that ECB runs correctly with loaded cedet 1.0 but the ECB-upgrading feature (see section 7.1 Downloading new versions of ECB and/or required packages) does not support autom. upgrading to latest available cedet versions. This will be first available after first stable release of the new cedet-library 1.0.

So, if the cedet 1.0 suite is loaded then the min- and max-version of semantic, eieio and speedbar (mentioned in the Requirements-section of the file `README') have no relevance! If the new cedet 1.0 suite should be used then just install and load cedet 1.0 like described in the cedet-installation-instructions and go one with step 3.

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

2. Read the file `README' in the ECB-directory and install the required semantic-, eieio- and speedbar-version(2).

   Please note: ECB maybe requires a newer version of these libraries than shipped with (X)Emacs. You have to install exactly a version ECB requires and also to make sure that the correct version is loaded into (X)Emacs!

   But ECB performs two autom checks:

   • At load-time: It checks if the packages semantic, eieio and speedbar are at least installed so ECB can be loaded. If not it offers to download and install them.

   • At start-time: It checks if the correct versions of semantic, eieio and speedbar are installed and gives you proper feedback. See Download required packages.

   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!

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'(3).

   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!

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 loadtime(4)):

   (require 'ecb)

   If you want to load the ECB first after starting it by ecb-activate (Advantage: Fast loading(5). 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 (X)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:

1. Reading the online help with ecb-show-help

   Maybe you are interested to read the online-help of ECB before first start.

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

3. 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 section 4.14 Interactive ECB commands).

1.2 How to set up Emacs for file parsing with ECB

Please note: Normally it should not necessary for you to bother with the following stuff unless you have problems getting ECB working correctly for you.

1.2.1 General hints for a correct setup

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(6). 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(7) are:

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.

1.2.2 Setting up semantic

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 semantic itself

   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! You have only to add the installation directory of semantic to your load-path (in an appropriate way)!

   Please note: If you setup semantic for yourself following the recommendations in the installation instructions of semantic then you have probably added code to your startup-file like:

   (setq semantic-load-turn-everything-on t) (require 'semantic-load)

   Be aware that this also enables the minor-modes semantic-show-dirty-mode and semantic-show-unmatched-syntax-mode where the former one highlights all code which has to be reparsed with dark background (which results in large portions of dark background ;-) and the latter one underlines all syntax which can not be parsed. Especially the former one can be really annoying.

   To switch off these modes you can add to your startup-file:

   (global-semantic-show-dirty-mode -1) (global-semantic-show-unmatched-syntax-mode -1)

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(8) 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 setq(9)!

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!

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

1.3 First steps after activating ECB 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 ecb-source-path RET(10). 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 . o or
   • using the menu "ECB".

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

   Here is also the chapter "Tips and tricks" very interesting!

4. Start working with ECB.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.