Building Metashell (detailed steps)

This guide helps you set up a development environment for working on Metashell. If you'd like to build it quickly, you can use the simple build steps.

Linux, FreeBSD and OpenBSD

  • Download the source code from github.
  • Run install_build_dependencies.sh to install the dependent tools and libraries or install the dependent libraries and tools:
    • Readline (or Libedit)
    • Termcap
    • CMake
    • Clang (with clang-tidy, clang-format)
    • Graphviz
  • Create the build directory
    • mkdir -p "bin/$(tools/detect_platform.sh --id)"
  • Build Clang with Templight
    • cd "bin/$(tools/detect_platform.sh --id)"
    • mkdir templight
    • cd templight
    • cmake ../../../3rd/templight/llvm -DLIBCLANG_BUILD_STATIC=ON -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_TERMINFO=OFF
    • make clang libclang libclang_static templight
  • Now compile Metashell. In the source directory run the following commands:
    • cd ..
    • mkdir metashell
    • cd metashell
    • cmake ../../..
      • Note: to use libedit instead of Readline add the -DUSE_EDITLINE=true argument to the above command line.
      • Note: if you don't want to link statically against libclang, you need to add -DCLANG_STATIC=false to the above command line.
    • make
    • To install it on the host run make install
    • To package it for Debian or Ubuntu run cpack -G DEB
    • To package it for OpenSUSE or Fedora run cpack -G RPM
  • To generate code-coverage statistics for unit tests run the following commands in the source directory instead the above ones:
    • cd "bin/$(tools/detect_platform.sh --id)"
    • mkdir metashell
    • cd metashell
    • cmake ../../.. -DENABLE_CODE_COVERAGE=true -DCMAKE_BUILD_TYPE=Debug
    • make
    • make test_coverage
    • You can find the test coverage statistics in the bin/$(tools/detect_platform.sh --id)/metashell/coverage directory.
  • To compile the source for profiling using gprof (g++ only):
    • cd "bin/$(tools/detect_platform.sh --id)/metashell"
    • cmake ../../.. -DENABLE_PROFILING=true
    • make
    • The binaries will now generate profiling data to gmon.out. Please see the gprof documentation for further information.

Clang and Templight

The source code of Metashell contains the source code of LLVM/Clang patched with Templight. The Templight patch can be found in the 3rd/templight/patch directory. The naming convention is templight_patch_r<SVN release it patches>.diff. To update the Clang version used:

  • Place a newer patch in the patch directory
  • Run the tools/get_templight.sh script

Windows

  • Download the source code from github.
  • Install CMake
  • Install Python
  • First you need to build Clang with Templight.
    • Start a command line on your Windows host and go into the source directory
    • Run md bin\windows_Win32\templight
    • Run cd bin\windows_Win32\templight
    • Run cmake ..\..\..\3rd\templight\llvm
    • Start Visual Studio 2013 and open the generated solution (3rd\templight\build\LLVM.sln)
    • In the BUILD menu choose Configuration Manager.... As Active solution configuration: choose Release and click on Close. This is needed to do a release instead of a debug build of Clang.
    • In Solution Explorer, inside Clang executables right-click on templight and choose Build.
    • You can optionally try building the rest of the projects, but Metashell does not need them.
  • Now you can build Metashell
    • Start a command line on your Windows host and go into the source directory
    • Run md bin\windows_Win32\metashell
    • Run cd bin\windows_Win32\metashell
    • Run cmake ..\..\.. -G "Visual Studio 12 2013".
    • CMake will generate a solution file for Metashell in the bin directory. Open it with Visual Studio 2013 and build it. You can do a debug or a release build (or both) against the release build of Templight.
    • After a successful build you can find the Metashell executables in bin\windows_Win32\metashell\app\metashell\Release\metashell.exe or bin\windows_Win32\metashell\app\metashell\Debug\metashell.exe depending on the build type.
    • Note that the system tests run lots of Metashell processes which create lots of temporary directories and files. Some anti-virus software seems to consider it harmful and block some these operations causing a number of tests to fail. If you experience that, temporarily disabling the anti-virus software can make the tests pass.
  • To generate an installer for Metashell:
    • Install NSIS.
    • Build Metashell following the above instructions (make sure you build the Release config).
    • Run cpack in the directory you run cmake as well.

Standard header files on Windows

The headers of Visual C++ are used on Windows, which requires Visual C++ to be installed on the host.

WinEditLine

Metashell uses WinEditLine on Windows. To simplify the Windows build, the source code of WindEditLine is redistributed as part of the Metashell source code and built together with Metashell. The content of the src directory of the WinEditLine source code can be found in the 3rd/wineditline directory. The content of the original CMakeLists.txt has been changed to build the code together with Metashell. If you want to upgrade WinEditLine to a newer version, you need to update these files.

Building Metashell on OS X

  • Download the source code from github.
  • Install the dependent tools:
    • CMake
    • XCode
    • The appropriate version of "Auxiliary tools for Xcode" which contains the PackageMaker compiler.
  • Create the build directory
    • mkdir -p "bin/$(tools/detect_platform.sh --id)"
  • Build Clang with Templight
    • cd "bin/$(tools/detect_platform.sh --id)"
    • mkdir templight
    • cd templight
    • cmake ../../../3rd/templight/llvm -DLIBCLANG_BUILD_STATIC=ON -DCMAKE_BUILD_TYPE=Release
    • make clang libclang libclang_static templight
  • Now compile Metashell. In the source directory run the following commands:
    • cd ..
    • mkdir metashell
    • cd metashell
    • cmake ../../..
      • Note: if you don't want to link statically against libclang, you need to add -DCLANG_STATIC=false to the above command line.
    • make
    • To install it on the host run make install as root.
  • To generate an installer package (.dmg):
    • Install the appropriate version of "Auxiliary tools for Xcode" which contains the PackageMaker compiler. On Mavericks this will be the 2012 late July version.
    • cpack

Building against custom Clang build

If you want to build Metashell against a different version of Clang or you have built Clang on your system and would like to use that instead of rebuilding it for Metashell, here is how you can do it.

Note that you should apply the Templight patch against your Clang.

Note that you need to build a static version of libClang. If you are building LLVM/Clang with CMake, you need to pass the -DLIBCLANG_BUILD_STATIC=ON argument to Clang's cmake.

Also note that Metashell is prepared for being built against the version of Clang you can find in the 3rd/templight directory. It is staticly linked against Clang and if you use a different version of Clang, the list of libraries to link against might be different. You can update it in cmake/Modules/FindClang.cmake.

You need to follow the manual build instructions of your platform and pass the following extra arguments to cmake:

-DCLANG_INCLUDEDIR=$LLVM/tools/clang/include -DCLANG_BINARYDIR=$CLANG_BIN/bin -DCLANG_LIBRARYDIR=$CLANG_BIN/lib

where

  • $LLVM is the path to the (top level) llvm directory of your Clang source tree.
  • $CLANG_BIN is the path to the directory where you have built the Clang binaries. This is $BUILD on Unix systems and $BUILD/<build mode> on Windows, where $BUILD is the build directory you were running cmake from and <build mode> is the build mode you choose in Visual Studio (eg. Debug, Release, etc).

To debug configuration issues, you can pass the -DCLANG_DEBUG=true argument to cmake. This will show you which version of Clang it found.