The following guide outlines how to quickly get started with using Git, building Emacs for debugging, and running Emacs in GDB (the GNU Project debugger).
Ensure Dependencies And Build Tools Are Installed
First of all, ensure that source packages are available. On Ubuntu or Linux Mint, it is recommended to use the Software Sources tool, since use of the command line depends on the distribution being used.
Enabling source code repositories on Ubuntu
On Debian-based distros (including Ubuntu and Linux Mint), install the following (checkinstall is useful if you want to later install your builds using ‘make install’):
sudo apt-get install build-essential checkinstall git-core
Then download the dependencies for Emacs using:
sudo apt-get build-dep emacs24
Other guides are available online for other distributions.
Installing ccache for Faster Rebuild Times (Optional)
Ccache is a tool that works with GCC, speeding up recompilation by caching previous outputs and detecting when the same compilation is being carried out again. This tool provides noticeable improvements when rebuilding after running the clean task (e.g. make clean; make).
To install it on a Debian/Ubuntu based distribution, use the commands below. It is important to add the /usr/lib/ccache to the path if you want ccache to wrap around runs to gcc but remember this is applied to all calls and may interfere with other compiler wrappers.
export PATH=/usr/lib/ccache:$PATH```
Make sure that the ccache directory is prepended before the existing path as in the export command above. Incorrectly using $PATH:/usr/lib/ccache would mean that existing compiler binaries would be given preference over the ccache symbolic links, and would be pointless.
If you don't want to add ccache to your path for all GCC builds, you can use ccache just for building Emacs by altering the CC option on ./configure, (more on configure in the build section):
```./configure CFLAGS='-Og -g3' CC='ccache gcc -std=gnu99'```
## Build and Install the Git Merge Driver for GNU Projects (Optional but Recommended If Merging)
Before downloading the Emacs Git repository, it is helpful to download and install the merge driver in order to prevent conflicts if you want to merge upstream. Configuring the changelog merges is outlined in a later section.
```git clone --depth 1 git://git.savannah.gnu.org/gnulib.git
cd gnulib
./gnulib-tool --create-testdir --dir=/tmp/gmerge git-merge-changelog
cd /tmp/gmerge
./configure
make
sudo make install```
## Cloning Emacs Repository from Savannah
Make sure you have some username and email set up in your Git config. If you have set up one previously for GitHub, that should suffice.
```git config --global user.name "Declan Kelly"
git config --global user.email "[email protected]"```
And then shallow clone (```--depth 1```) the Emacs repository from Savannah and navigate to directory:
```git clone --depth 1 git://git.sv.gnu.org/emacs.git
cd emacs```
## Configuring Changelog Merges (Optional but Recommended If Merging)
To configure the merge and diff actions for GNU-style changelogs, simply append the following to two files in the project's working directory:
.git/config:
```[merge "merge-changelog"]
name = GNU-style ChangeLog merge driver
driver = /usr/local/bin/git-merge-changelog %O %A %B
[diff "lisp"]
xfuncname = "^(\\(.*)$"
[diff "texinfo"]
xfuncname = "^@node[ \t][ \t]*\\([^,][^,]*\\)"```
.git/info/attributes:
```ChangeLog merge=merge-changelog
*.c diff=cpp
*.h diff=cpp
*.el diff=lisp
*.texi* diff=texinfo```
## Build Emacs
And now for the moment of truth. With GCC 4.8 or later use the following:
```./autogen.sh
./configure CFLAGS='-Og -g3'
make bootstrap```
The build process should complete in 20-40 minutes. For older GCC versions or some non-GCC compilers, replace CFLAGS with ```'-O0 -g3'```.
If you have errors similar to below on ./configure, please see [this guide for resolving source dependencies on Ubuntu](https://help.ubuntu.com/community/CompilingEasyHowTo#Step_3:_Resolving_Dependencies.).
```configure: error: Library requirements (...) not met, ...```
## Running Emacs in GDB
Navigate to the source folder (which contains .gdbinit, a file of commands to run when gdb is started), and run the following command:
```cd src
gdb -tui --args emacs -Q```
You will more than likely get a security warning about declined auto-loading for the .gdbinit. Information on this security restriction is available in the Debugging with GDB documentation.
When the (gdb) prompt appears, type run:
```(gdb) run```
Tada! We now have an interactive GDB session that uses the ncurses-based user interface.
The use of the ```-Q``` option for Emacs is important, it is shorthand for ```-q --no-site-file --no-splash```, which prevents loading the init file, the site-wide startup file, and also prevents loading the splash screen. This is recommended for reproducing a bug found in Emacs to ensure that it is not caused by your own .emacs.d customisations.
To quit, just close Emacs and type the following in the (gdb) prompt:
```(gdb) quit```
Of course, you can set up GDB sessions in any IDE of your choice, or Emacs ;)
---
*Note:* If you decided to build from Debian or other sources instead of the Git Savannah repository above, Emacs may not be located in the src directory. You could use the following to locate the Emacs binary from the project folder:
```find . -executable -name "emacs*" -type f```
You will need to cd to the src folder as .gdbinit is located there, but pass the path to emacs when running gdb if the binary executable is in a different folder:
```gdb -tui --args path/to/emacs/binary/emacs -Q```