Package: meson-vs-gen
Tools for generating VisualStudio solution from meson introspection files.
The usecase is when you want to use theninjabackend,
but edit or debug the project using the VisualStudio IDE.Requirements: you need a C or C++ meson project, with at least one
configured build directory. You need meson 1.2.0 or higher.Using the command lineA command line interface is provided through thevsgencommand.Generating projectTheprojectcommand allows to generate one .vcxproj file from a configured
meson project:vsgen project [--target TARGET] [--update] [--sourcedir SOURCEDIR] [--outputdir OUTPUTDIR] [--builddir [CONFIG:]BUILDDIR, ...] NAMETheNAMEis the name of the generated .vcxproj. It can also be a full path.
By default, it will look for a target with the same name as the project,
unless--targetoption is provided. Project sources should be in current dir,
or specified with--sourcedir. Build directory must be provided using--builddiroption. It can be a path relative to SOURCEDIR. The config is deduced automatically,
but the config name to use can be specified usingCONFIGNAME:prefix to the build dir
(e.g.--builddir debug:/path/to/debug/build).Files are generated in--outputdir, unless a full path is provided forNAME.
By default, theOUTPUTDIRwill be the current directory.If--updateoption is provided, existing .vcxproj will be updated instead of
being rewritten. This is useful to add a new build config to an existing project.Example:vsgen project -t mylib -o vs -b build/debug -b build/release MyProjectwill generatevs/MyProject.vcxproj, with configs for debug and release,
for themylibbuild target.Generating solutionThesolutioncommand allows to generate a .sln file that includes one or many projects.vsgen solution [--project [TARGET:]PROJECT, ...] [--projectdir PROJECTDIR] [--update] [--sourcedir SOURCEDIR] [--outputdir OUTPUTDIR] [--builddir [CONFIG:]BUILDDIR, ...] NAMETheNAMEis the name of the generated .sln file. It can also be a full path.The--projectoption allows to specify the name or the path of a project to include.
It may be specified multiple times. If not specified, all projects from PROJECTDIR are
included.TARGETif the name of the build target to use, if different fromPROJECT.
If not specified, projects for all build targets are generated.If specified,PROJECTDIRwill be a sudir ofOUTPUTDIRcontaining the project files.Other options are similar to those of theprojectcommand.Using configuration fileThegeneratecommand allows the generation of complex solutions, using a .yaml
configuration file.vsgen generate [--sourcedir SOURCEDIR] [--outputdir OUTPUTDIR] CONFIGFILECONFIGFILEis the path to the .yaml config file. Other options are similar
to those ofprojectcommand.The config file contains the following keys:outputdir: (optional) Where to generate the solution files, if not specified
on the command line. Default is to use current dir.projectdir: (optional) Name of a subdirectory where to write project files.case_insensitive_targets: (optional) If true, lower case targets match project names containing uppercase characters.only_relative_files: (optional) If true, do not add files outside target source dir
(i.e. where target meson.build file is located) into the project.include_from_env: (optional) If true, will useINCLUDEenv var for system include path.
If 'auto', will useINCLUDEif it is defined.
If false (default), will no rewrite the include path.
This is useful when using a different build tools version that the IDE.configs: map build directories to config names.archs: (optional) map cpu_family to arch name. If not specified,
use the cpu_family as the arch name.projects: The projects to generate. See project specifications below
for more details.solutions: The solutions to generate. See solution specifications below
for more details.Project specificationsFor each project, the key is the name of the project to generate.
If the key is*, the settings apply to all unlisted projects,
and is used as default config.If the value is a boolean,truemeans to generate the project with default settings,
andfalsemeans to not generate that project.If the value is a map, the following keys are recognized:target: the build target name.truemeans to use the project name as the target name.
If target name begins withdep:, this is the name of an internal dependency object,
used for a header only project. This project will not compile, but will display files
from that dependency.allis used for a target that generates all targets.subdir: if specified, put the generated project into that subdir of the project dir.Solution specificationsFor each solution, the key is the name of the solution to generate.Value is a map with the following keys:projects: A list of projects to include into the solution.
If the value is a string, this project is included (must be listed into
theprojectssection). If the value is a map, it map a directory name
with a list of projects. This allow to put projects into logical directories
in the solution. The structure is recursive. If the value is*, it means
to include all projects not referenced elsewhere in the solution. If the value
is a map with a boolean value, the key is a project name, and it is included if
the value istrue, and explicitly skipped if the value isfalse.build_solution: The value is the project (or a list of projects) invoked when
building the solution.runsettings: (optional) Iftrue, generates runsettings for all executables.
Otherwise, map a wildcard with runsettings options. This allow special configurations
for running tests with Google Test Adapter.Using the APIThe Generator objectvsgenpackage can also be used as an API, from a python script:from vsgen.api import Generator.The generator object takes 3 arguments:vspath: The path where to generate the solution and project files
(absolute, or relative tobasedir)basedir: (optional) The base path for other paths. Default is current dir.projectdir: (optional) The subdir where to generate projects (relative tovapath)You can also modify or override thecpu_archdictionary,
mapping cpu_family to arch name for the solution and projects.The next step is to callset_config. The method takes the following arguments:builddir: meson build dir, absolute, or relative toself.basedir.name: (optional) config name to use (default is builddir name).use_include_from_env: (optional) IfTrue, will use theINCLUDEenv var
as system include path.Theprojectmethod is used to create aVcxProjobject. Arguments are:name: The project name.target: (optional) The build target name. Default is project name.subdir: (optional) Subdir (relative to projectdir) where to write the project.
IfTrue, the subdir is the project name. IfFalse, no subdir is used.update: (optional) IfTrue, update existing project instead of overwriting it.
Default isTrue.only_relative_files: (optional) IfTrue, will not reference source files that
are not relative to the project root.The method returns aVcxProjobject.Thesolutionmethod is used to create aSolutionFileobject.
Arguments are:name: The solution name.update: Whether to update existing files instead of overwriting them.The ConfigFile objectThis is a high-level interface to deal with complex solutions
managed by a configuration file. See [Using configuration file] above
for more details about the configuration file syntax.from vsgen.configfile import ConfigFile
from pathlib import Path

cf = ConfigFile('path/to/config.yaml').load()  # load config file

basepath = Path('project/basepath')
outputpath = Path('project/outputpath')

cf.analyse(basepath)  # analyse project introspection data
cf.generate(basepath, outputpath, update=True)  # generate project and solution filesThe SolutionFile objectYou usually create theSolutionFileobject using theGenerator.Next step is to add projects to the solution:sln.add_project(project, subdir, build_solution_target=False)projectis aVcxProjobjectsubdiris an optional string if you want the project into a logical
subdirectory in the solution.build_solution_target: ifTrue, this project is build when
generating the whold solution. This is usually used for thealltarget only.Finally, you can write the solution file:sln.write()The VcxProj objectTo write the .vcxproj file:prj.write()/The RunSettingsFile object[https://learn.microsoft.com/en-us/visualstudio/test/configure-unit-tests-by-using-a-dot-runsettings-file?view=vs-2022]This allow to configure and write a runsettings file.from vsgen.runsettings import RunSettingsFile
from pathlib import Path

rsfile = RunSettingsFile(Path('path/to/runsettings/file'))
rsfile.add_solution_setting(name, value)  # add a setting for whole solution
rsfile.add_project_setting(name, value, regex)  # add a setting for projects
                                                # matched by regex

rsfile.write()