Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
CDT/Meson/User Guide
{{#eclipseproject:tools.cdt}}
Contents
Introduction
The Meson feature for Eclipse is an optional feature of the CDT (C/C++ Development Tools) that adds support for maintaining and building C/C++ projects that use the Meson build system. The Meson build system is akin to Autotools in that a project is configured before building. Like Autotools, configuration involves testing the build system and toolsets supported. Once configured, the project is built by a second tool, akin to the Make tool used in Autotools. While Meson supports more than one Make-like tool to build the project, the CDT Meson plug-ins currently only have support for "ninja".
The configuration data for the project is stored in a file called: "meson.build". This file contains directives that are interpreted by the meson command. Directives include which languages are used, what executables/targets are created, sources, special configuration options, and any special build-time tests among other things. Many tests are automatic so the configuration file does not require much.
The following is a sample meson.build file:
project('hello', 'c')
executable('hello', 'hello.c')
This file tells meson that the project name hello is a C project and that it creates a single executable called hello which is formed from hello.c. Meson will find the C compiler, etc.. needed to build this project on this build machine.
Running meson in the directory containing meson.build will create a ninja.build file in the build directory (or specified build directory).
For more details see: https://mesonbuild.com/
Supported Environments
The Meson plug-ins work on all the platforms that CDT supports.
Creating a Meson Project
To create a Meson project, use File -> New -> C/C++ Project Either find the Meson projects in the list of all projects or click on Meson in the left-hand column to filter out non-Meson projects.
There are two choices: Empty Project or Meson Project. Since Meson projects configure whether they support C, C++, or both, there is no need to specify a language as is done for the old Managed Build projects. The Empty Project template means that no files will be supplied to the new project while the Meson Project is a sample C hello world program that uses Meson for configuring the build.
To use a Meson project you have checked out in your system, choose the Empty Project template and then change the location of the project to point to where the project exists on your system.
The Meson plug-ins will perform builds in the build directory with a separate directory per configuration. (e.g. {$Project}/build/default). By default, there are two basic configurations, run and debug.
Configuration
To specify configuration options, go to Project -> Properties -> Meson
The meson command without arguments can only be run for a build directory once. After it has been run once, a user may use the meson configure command to change some parameters of the configuration. Thus, there are two UI pages presented to the user:
- specifying options for meson prior to the first configuration/build
- specifying options for meson configure after the project has been configured at least once
Before the first configuration, the Meson plug-ins use the output of the meson -h command and parses the output to create the UI page.
Parameters that have a set of values are presented as a combo, boolean options are presented as a checkbox, and string options are presented as text boxes. In addition, the user may specify Project specific options and Environment variables. Project specified options are created in a special file called meson_options.txt and are set like a compiler flag (-Dname[=value]). The project specified options are not parsed by the Meson plug-ins so the user must know what is possible ahead of configuration. Environment variables are specified as NAME=VALUE pairs and are used during the meson command (e.g. CC=/my/dir/gcc).
By default, the meson buildtype parameter is set based on the active configuration launch type (run = release, debug = debug). The user can override this prior to configuration and change the build type as needed (e.g. debugoptimized or plain). Likewise, the user can simply change the launch type using the Launch bar.
After configuration, the Meson plug-in uses the output of meson configure to get the set of options that can be changed and parses them to create the UI page. Project options are returned as part of the output and are parsed like any other option (presented either as a combo, checkbox, or text entry).
Hitting the Apply or Apply and Close buttons will end up running the meson configure command immediately with any options that have been changed in the dialog.
Building
There are a number of ways to build the Meson project.
Using the Launch bar, just hit the hammer: icon and the project will be built appropriately for the launch type. If the project is unconfigured, any options specified in the Property Page are used to run the meson command. Otherwise, just the buildtype is defaulted according to the launch target in the Launch bar (run = release, debug = debug).
If any errors occur during the meson stage, they are reported and the build is stopped. Otherwise, the ninja command is run and the results output to the build console.
The build can also be started using the Eclipse hammer: icon or via Project -> Build.
Cleaning the project is done using Project -> Clean. The clean operation performs a meson clean command for the active configuration.
If the user needs to build a different target (e.g. install) or specify environment variables to ninja, then they must use the Run ninja context menu item that is available when right-clicking on a project or file in the project in the Project Explorer View. This brings up the Run Ninja dialog.