Description: Official website of Cling
Keywords: cling, interactive compiler interface, interpreter, clang, LLVM

# Cling Website

## Interactive Compiler Interface

- Home
- Download
- News
- Docs
  Documentation
  Developer
  - Doxygen
  - Extensions
  - Error Recovery
  - Late Binding
  End User
  - User Manual
  - Status of ObjectiveC[++]
- Get Involved

# Cling

Welcome to our interactive C++ interpreter, built on the top of LLVM and Clang libraries. Its advantages over the standard interpreters are that it has command line prompt and uses just-in-time (JIT) compiler for compilation. An interactive prompt is usually referred to as a read eval print loop or repl. Many of the developers (e.g. Mono in their project called CSharpRepl) of such kind of software applications name them interactive compilers.

One of Cling's main goals is to provide contemporary, high-performance alternative of the current C++ interpreter in the ROOT project - CINT. The backward-compatibility with CINT is major priority during the development.

## How to use it

You can start typing not only C++ top level declaratons but statements, too.

    **** Welcome to the cling prototype! ****
    * Type C code and press enter to run it *
    * Type .q, exit or ctrl+D to quit       *
    *****************************************
    [cling]$

Statements and expressions could take more than one input line. The interactive prompt changes from "[cling]$" to "[cling]$ ?".

    [cling]$ #include "math.h"
    [cling]$ #include "stdio.h"
    [cling]$ for (unsigned i = 0; i < 5; ++i) {
    [cling]$ ?   printf("%f\n", sin(i));
    [cling]$ ?   }
    0.000000
    0.841471
    0.909297
    0.141120
    -0.756802

## Grammar

Cling is able to parse everything that clang can. Current clang status can be found here. At the moment, there are use cases only for C++ that's why cling is best in working with C++. Clang has support of C, objC, objC++ and we are looking forward to having more use-cases and extend our tool in that direction.

Cling has internal commands, which can change its behavior at runtime. Those commands usually start with dot (.):
- .I <path> - Adds an include path;
- .x <filename> - #include-s the filename; and calls function called filename();
- .L <libname> - Loads libname or #include-s the libname if libname is file;
- .@ - Cancels the multiline input;
- .printAST - (DEBUG ONLY) Turns on the printing of the compiler's abstract syntax tree (AST);
- .dynamicExtensions - Turns on cling's dynamic extensions. This in turn enables the dynamic lookup and the late resolving of the identifier. With that option cling tries to heal the compile-time failed lookups at runtime;

## Details

### Command line

The interactive prompt supports an emacs-like command line editor, just like bash terminal, which makes it easy to integrate and use. Cling uses TextInput and doesn't depend on ncurses.

Autocompletion should be coming soon!

### #Include Declarations

Cling allows #include-s to be not only before the declarations. The includes could be mixed with other declarations. For example:

    [cling]$ #include "math.h"
    [cling]$ sin(1)
    (double const) 8.414710e-01
    [cling]$ #include "stdio.h"
    [cling]$ printf("%f\n", sin(1));
    0.841471

More statements could be combined using semicolon (;). This doesn't stay when the command is #include The following example is invalid:

    [cling]$ #include "math.h"; sin(1)

The same rules are applicable for the other preprocessor directives (commands starting with # - such as #define)

### Variable Declarations

Cling allows statements to be entered onto the global scope. In order to be compiled and executed by the compiler these statements need to be wrapped into functions, which body contains the statement and afterwards to run the function. The semantics of the statements that declare variables is that variables should be accessed by other statements. If the statement that declare variable is wrapped into function the variables won't be accessible from outside anymore. In this case variables are extracted onto the global scope.

TODO: There should be dedicated entry for that in the docs

### Builtins

Cling starts with very few builtins loaded. Users could extend the available builtins via extending the RuntimeUniverse.h, which is loaded at cling's startup.