C-xrefactory — A refactoring tool for C/Yacc and Emacs

TL;DR

c-xrefactory is a free Emacs refactoring tool and code browser for C & Yacc.

[!CAUTION] As c-xrefactory is undergoing radical refactorings and changes, and doesn't have tests for all features, occasional hiccups are possible. I use it almost everyday and the stable version, which you get if you install as per below, has passed all tests. But YMMV.

Install

The easiest, and currently only supported, way to install is using el-get:

M-x el-get-install<ENTER>c-xrefactory<ENTER>

[!TIP] You can easily install el-get in your running emacs using a snippet from el-get's GitHub repo, but don't forget to add the el-get pieces to your emacs init.

Example Use

Place cursor on an identifier and go to definition (F6), navigate between occurrences (F3, F4), refactor (F11) with rename, mark some code and extract function. Your C programming and code will never be the same. Some highlights:

• navigate through all usages of any type of symbol
• rename any type of symbol, variable, macro, parameter, or Yacc grammar rule
• add or delete function parameter
• extract function or macro
• detect unused symbols locally or in the complete project

When installed correctly there will be an Emacs menu called C-xref for easy access to most functions.

Tutorial

Once you have that menu in Emacs you can try the Tutorial under C-xref->C-xref Misc. It will automatically create the tutorial project files in a temporary directory and open the initial file. Then just follow the instructions for a quick walk-through of what c-xrefactory can do.

Setup

If your Emacs runs in a "standard" *ix-like environment with bash, make, cc etc. you probably don't need anything in particular.

c-xrefactory works with recent Emacsen on Linux, including WSL, Cygwin, Msys2-MSYS (but not Msys2-MingW*) and MacOS/Darwin.

For Windows I really recommend doing your development in WSL (especially WSL2). You can setup c-xrefactory as described above and run Emacs in a terminal window without any problems.

To use Emacs in a graphical environment from WSL (in an X11 window) you need a Windows X11 server like VcXsrv (my recommendation), X410 (from the Windows Store), Xming or, if you already have MobaXterm, that also comes with an X11 server. Then setup the server according to these instructions.

Features and notes

WORK IN PROGRESS!

Whatever documentation there is can be found here. We are using C4 and Structurizr to document the architecture as best we can.

Yacc special features

C code inside semantic actions in a Yacc file will be analysed so that you can (mostly) navigate symbols even inside them.

Non-terminals (rule names) can be navigated and completed as if they were any other symbol. Furthermore the special symbol $<n>, where <n> is a number referencing symbol <n> in the rule can also be navigated. This is extra handy with F6 to be sure that you referenced the terminal or non-terminal that you meant to.

Unfortunately there are no refactorings of Yacc rules possible (but that would be a cool project!). But you can of course do all the C refactorings you want from inside the C code in the semantic actions.

LSP

As noted in one issue, a natural development would be to support LSP (The Language Server Protocol), but that is still far out of reach. A lot of refactoring needs to be done to clean up the current modules and protocol to get closer to that point.

Java notes

[!IMPORTANT] Java support has now been removed since there are far better options now.

The current Java grammar has not been updated from Java 1.4, but since c-xrefactory recovers gracefully that is not a major problem except for the fact that you can't for certain navigate all symbols inside construct that was introduced in later Java versions.

You need to have a JRE installed so that it can be found. If it's Java 8 it will also be parsed for all Java standard library symbols. Unfortunately later versions does not store JRE in a standardized format (which was Jar-files with class files) so c-xrefactory cannot read it. You can still compile with Java > 8 and use c-xrefactory with a Java 8 JRE.

NOTE: As there are good Java tools available with refactoring support I'm thinking of removing all Java support from c-xrefactory since that complicates a lot of things. And some of the cool solutions don't work any longer, like navigating Java library symbols by loading the jar-files that were part of any Java install up to Java 8.

Help!

This code is pre-historic legacy. It seems to have been born in a world of copy-paste-hack-and-debug, there were no unit tests, or any tests at all for that matter.

I'm on a long-time quest to resurrect this code to understandable, maintainable and developable standard. This is hard work, difficult and time consuming, as it is almost impossible to understand what anything does. At this point we have reached almost 75% test coverage which makes me confident in refactoring many things.

If you think you can help, I'll be happy to take it, even if it is only adding one line of understanding in the wiki...

Development and Documentation

There are some information about my current understanding of this beast in the design documentation. And there is a budding user manual. Those documents are continually published into the C-xrefactory documentation site.

These documents are in no means complete, or perhaps not even readable, but are attempts to continually collect bits and pieces of information from old documents and newly found knowledge.

The information stored in the wiki has been transferred into these documents and the wiki has been removed.

The Story

Once apon a time there was www.xref.sk, a site promoting possibly the worlds first refactoring browser to cross the "Refactoring's Rubicon". That site seems to be going up and (mostly) down and there has been no support for many years, but it seems that www.xrefactory.com is now a better and more stable URL to the original Xrefactory, where it is still available.

At that time it had a free Java and C version, and also a paid C++ version. Development seems to have been headed by a Marián Vittek.

Marián made a C-version, c-xref, available under GPL already 2009 on SourceForge. The reason seems to have been to allow parallel installations of free and non-free versions. c-xref seems to be intended to be limited to C and Emacs. Actually it was not. It was all but identical to the original full/free C/Java refactoring browser from www.xref.sk except for extensive name changes. So Java was also still supported, at least Java 1.4.

During many years I have worked on this off and on to improve it and extend the support for more C refactorings. It is still in flux but fully usable.

About This Clone

As I'm almost dependent on this and refactoring tools for C is sadly missing, I decided to pick this up and work a bit on it, and maybe even give it more visibility, by moving it to GitHub.

No-one would be more happy than me if the C++ version was also put in the public domain.

If someone is in contact with Marián, please inform him and ask him to contact me. Perhaps we can create something great from this, together with others who might be interested.