Valencia

Valencia is a plugin that turns gedit into a lightweight IDE for Vala. The Valencia  Web page gives a brief overview of Valencia and its capabilities. This Wiki page has complete documentation on using Valencia.

Mailing list: Send a message with a subject: of subscribe to  valencia-request@lists.yorba.org or go to  http://lists.yorba.org/cgi-bin/mailman/listinfo/valencia.

Building and installing

To build Valencia, you'll need to have the following programs and libraries installed:

•  valac, the Vala compiler.
  • Valencia depends on the valac libraries for system vapi directory information; if valac is not installed, Valencia may not function correctly!
•  gedit
•  libvte

On Ubuntu (and perhaps Debian), you can install the required build dependencies like this:

sudo apt-get install valac libvala-dev gedit-dev libgee-dev libvte-dev

You can download the latest source release at  valencia-0.3.0.tar.bz2 . Or check out the latest code (possibly unstable) at svn://svn.yorba.org/valencia/trunk. Then run make and make install. (Do not run sudo make install. Valencia installs in your ~/.gnome2/gedit directory, and if you install as root the permissions will be wrong.)

To enable Valencia in gedit, go to Edit ▸ Preferences ▸ Plugins and check the Valencia checkbox.

Using Valencia

Jumping to symbols

To jump to the definition of any symbol in your project, place the cursor on the symbol name and choose Search ▸ Go to Definition or press F12. Valencia will jump to the position where the symbol is defined. Valencia can jump to variables, fields, methods, classes, interfaces and namespaces. Symbol jumping is context sensitive: if you place the cursor on the word bar in the expression foo.bar() and choose Go To Definition, Valencia will find the appropriate implementation of bar() for the object foo. After jumping to a symbol, you can browse backward and forward up to the most recent symbol to which you have jumped via the Search ▸ Go Back and Search ▸ Go Forward commands (Alt+Left and Alt+Right).

The first time you jump to a symbol definition in a large Vala project (such as the valac compiler sources), Valencia will display a progress dialog as it indexes Vala source files. All subsequent symbol jumps should be fast.

Valencia parses system vapi files such as glib.vapi and gtk.vapi, allowing you to jump to symbols defined in any vapi file defined in the default system directory.

When Valencia is enabled, the gedit status bar displays the class name containing the current cursor position. This can help you tell you what class you've ended up in after jumping to a symbol definition.

The Search ▸ Go to Outer Scope command (Ctrl+F12) jumps to the method containing the cursor position. If the cursor is not inside a method, this command jumps to the class containing the cursor position. So you can run this command once to jump to the enclosing method, and then again to jump to its enclosing class.

Valencia includes a symbol browser pane in the gedit sidebar. The symbol browser lists only symbols in your project. It looks within local namespaces to find all top-level symbols, and does not include symbols found within scopes other than namespaces (e.g. methods or fields found in classes). To see the symbol browser pane, choose View ▸ Side Pane, then click the magnifying class icon tab at the bottom of the sidebar. To search for a symbol, choose Search ▸ Find Symbol... or press Ctrl+Alt+S to go to the search entry box, where you can type the name of the symbol which you want to find.

Tooltips and Autocomplete

Both tooltips and autocomplete use the same menu item (Search ▸ AutoComplete) and shortcut key (Ctrl+Space). These features are context-sensitive and must be invoked manually to be used. You can cancel a tooltip or autocomplete dialog any time by pressing escape when it is on the screen. When trying to invoke autocomplete, sometimes the cursor may be in the context to get a tooltip. Simply invoke autocomplete again and a list will appear.

To see a tooltip for any method within the project, place the cursor anywhere within a method call after the opening parenthesis, and invoke autocomplete. To get an autocompletion list for an incomplete symbol, invoke autocomplete when the cursor is at the end of the symbol. If the cursor is inside a symbol, it will attempt to get an autocompletion list for the partial symbol before the cursor. Invoking autocomplete at an empty space will bring up a list of all members of the global and using namespaces. You can scroll through the list with the up and down arrows, browse by pages with pageup and pagedown, and skip to the beginning and end of the list with the home and end keys, respectively.

Building your project

To build your project, choose Project ▸ Build or press Ctrl+Alt+B. The build will occur in your project's root directory (see The project root below). Valencia runs make to perform the build; you must provide a Makefile that invokes valac on your source files. (You can write a Makefile by hand, or can generate one using a tool such as automake). The build output will appear in a pane at the bottom of the gedit window. You can double-click on any build error to jump to the source line where it occurred. You can also use the Search ▸ Next Error and Search ▸ Previous Error commands (Ctrl+Alt+N and Ctrl+Alt+P) to move between build errors.

If you do not use make, or want to specify command line options (e.g. make -j2), you can tell Valencia a new command to use. Either choose Project ▸ Settings or press Ctrl+Alt+T to go to the settings dialog, where you can specify your own custom build command.

You can also clean the project's build output by choosing Project ▸ Clean or pressing Ctrl+Alt+C. Valencia by default runs make clean, but if you do not use make, or would rather run a different command (e.g. rm *.o *.so), you can also specify a custom clean command to use in the settings dialog, just like with the build command.

Running your program

After you've built your project, you can launch the generated program from within gedit. To do this, you must add a variable definition PROGRAM=name to your Makefile, where name is the name of the program generated by your Makefile. To run your program, choose Project ▸ Run or type Ctrl+Alt+R. Valencia will launch your program and display its output in a pane in the gedit window.

The Project ▸ Run command is somewhat limited: it does not work for Autotools-based projects and it's not currently possible to specify arguments to be passed when running your program.

The project root

In Valencia, a project consists of a set of Vala files, plus an optional Makefile used for building.

If all of your Vala source files are in a single directory, you don't need to specify a project root in any way. By default, when you open any source file, Valencia will let you browse to symbols in all other source files in the same directory.

If your project spans multiple directories, your project's root directory must contain either of the following:

• a Makefile containing the definition BUILD_ROOT = 1
• a file named configure.ac or configure.in

When you open any source file below the root directory, Valencia will find the project root and will consider the project to include all Vala (and .vapi) source files below the root.

Future features

The following features are planned but not yet implemented for Valencia:

• Alternate build systems: There are other build systems besides autotools and make. Valencia should be flexible enough to allow the user to specify an alternate build system other than the default 'make'.
• C support: Thanks to Vala's close relationship with C, many times in order to investigate the source code of libraries bound to Vala or simply to debug generated code, searching through C code is inevitable. It would be nice to extend Valencia's parser to support browsing C symbols to ease the transitions between the two languages.
• Autocomplete enhancements: Autocomplete is a nice feature, but it could use several enhancements to make it even more streamlined with features like: type identifiers like full declarations or icons for completion suggestions, context-sensitive lists to avoid exposing nonstatic and protected/private members of classes, grouping suggestions by the most relevant (nested) scope.
• Debugger: it might be nice to build a front-end to GDB which works as part of Valencia inside gedit. It's not completely clear whether we'll do this, since existing front-ends such as Nemiver seem to work somewhat reasonably well for debugging Vala code today.

Other languages

Valencia was designed for the Vala language, but Vala and C# are so syntactically similar that Valencia also works fine with most C# code (and, in fact, Valencia will accept files with a .cs extension).

It would not be difficult to extend the Valencia parser to support Java; we'd like to do this.

Architecture

Valencia contains a lightweight Vala scanner/parser which understands only as much of Vala as is necessary for symbol browsing. The first time you jump to any symbol in a Valencia project, Valencia finds all source files in your project and parses them. Valencia writes no files to disk: the parse tree for each source file is stored in memory, and is regenerated each time you run gedit.

Whenever you save a source file to disk, Valencia reparses it. In addition, each time you jump to a symbol definition, Valencia reparses any source files which have been modified but not yet saved. So symbol browsing always reflects your program as it exists in gedit, whether or not source files have been saved to disk.

We may add more details about Valencia's architecture here at some point. If you're interested in working on the Valencia code and have questions about how anything works today, don't hesitate to ask questions on the Valencia  mailing list.