Tools for generating VisualStudio solution from meson introspection files.
The usecase is when you want to use the `ninja` backend,
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 line
A command line interface is provided through the `vsgen` command.
### Generating project
The `project` command allows to generate one .vcxproj file from a configured
meson project:
`vsgen project [--target TARGET] [--update] [--sourcedir SOURCEDIR] [--outputdir OUTPUTDIR] [--builddir [CONFIG:]BUILDDIR, ...] NAME`
The `NAME` is 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 `--target` option is provided. Project sources should be in current dir,
or specified with `--sourcedir`. Build directory must be provided using `--builddir`
option. It can be a path relative to SOURCEDIR. The config is deduced automatically,
but the config name to use can be specified using `CONFIGNAME:` prefix to the build dir
(e.g. `--builddir debug:/path/to/debug/build`).
Files are generated in `--outputdir`, unless a full path is provided for `NAME`.
By default, the `OUTPUTDIR` will be the current directory.
If `--update` option 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 MyProject
```
will generate `vs/MyProject.vcxproj`, with configs for debug and release,
for the `mylib` build target.
### Generating solution
The `solution` command 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, ...] NAME`
The `NAME` is the name of the generated .sln file. It can also be a full path.
The `--project` option 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. `TARGET` if the name of the build target to use, if different from `PROJECT`.
If not specified, projects for all build targets are generated.
If specified, `PROJECTDIR` will be a sudir of `OUTPUTDIR` containing the project files.
Other options are similar to those of the `project` command.
### Using configuration file
The `generate` command allows the generation of complex solutions, using a .yaml
configuration file.
`vsgen generate [--sourcedir SOURCEDIR] [--outputdir OUTPUTDIR] CONFIGFILE`
`CONFIGFILE` is the path to the .yaml config file. Other options are similar
to those of `project` command.
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 use `INCLUDE` env var for system include path.
If 'auto', will use `INCLUDE` if 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 specifications
For 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, `true` means to generate the project with default settings,
and `false` means to not generate that project.
If the value is a map, the following keys are recognized:
- `target`: the build target name. `true` means to use the project name as the target name.
If target name begins with `dep:`, 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.
`all` is used for a target that generates all targets.
- `subdir`: if specified, put the generated project into that subdir of the project dir.
#### Solution specifications
For 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
the `projects` section). 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 is `true`, and explicitly skipped if the value is `false`.
- `build_solution`: The value is the project (or a list of projects) invoked when
building the solution.
- `runsettings`: (optional) If `true`, 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 API
### The Generator object
`vsgen` package 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 to `basedir`)
- `basedir`: (optional) The base path for other paths. Default is current dir.
- `projectdir`: (optional) The subdir where to generate projects (relative to `vapath`)
You can also modify or override the `cpu_arch` dictionary,
mapping cpu_family to arch name for the solution and projects.
The next step is to call `set_config`. The method takes the following arguments:
- `builddir`: meson build dir, absolute, or relative to `self.basedir`.
- `name`: (optional) config name to use (default is builddir name).
- `use_include_from_env`: (optional) If `True`, will use the `INCLUDE` env var
as system include path.
The `project` method is used to create a `VcxProj` object. 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.
If `True`, the subdir is the project name. If `False`, no subdir is used.
- `update`: (optional) If `True`, update existing project instead of overwriting it.
Default is `True`.
- `only_relative_files`: (optional) If `True`, will not reference source files that
are not relative to the project root.
The method returns a `VcxProj` object.
The `solution` method is used to create a `SolutionFile` object.
Arguments are:
- `name`: The solution name.
- `update`: Whether to update existing files instead of overwriting them.
### The ConfigFile object
This 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 files
```
### The SolutionFile object
You usually create the `SolutionFile` object using the `Generator`.
Next step is to add projects to the solution:
```
sln.add_project(project, subdir, build_solution_target=False)
```
- `project` is a `VcxProj` object
- `subdir` is an optional string if you want the project into a logical
subdirectory in the solution.
- `build_solution_target`: if `True`, this project is build when
generating the whold solution. This is usually used for the `all` target only.
Finally, you can write the solution file:
```
sln.write()
```
### The VcxProj object
To 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()
```
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/optelgroup-public/meson-vs-gen",
"name": "meson-vs-gen",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<4.0",
"maintainer_email": "",
"keywords": "visualstudio,meson",
"author": "Charles Brunet",
"author_email": "charles.brunet@optelgroup.com",
"download_url": "https://files.pythonhosted.org/packages/f5/b4/89ea6096ec036ac815ced1b90662803ced4e71f8e625248ff47adbc33340/meson_vs_gen-0.5.2.tar.gz",
"platform": null,
"description": "Tools for generating VisualStudio solution from meson introspection files.\nThe usecase is when you want to use the `ninja` backend,\nbut edit or debug the project using the VisualStudio IDE.\n\nRequirements: you need a C or C++ meson project, with at least one\nconfigured build directory. You need meson 1.2.0 or higher.\n\n\n\n## Using the command line\n\nA command line interface is provided through the `vsgen` command.\n\n\n### Generating project\n\nThe `project` command allows to generate one .vcxproj file from a configured\nmeson project:\n\n`vsgen project [--target TARGET] [--update] [--sourcedir SOURCEDIR] [--outputdir OUTPUTDIR] [--builddir [CONFIG:]BUILDDIR, ...] NAME`\n\nThe `NAME` is the name of the generated .vcxproj. It can also be a full path.\nBy default, it will look for a target with the same name as the project,\nunless `--target` option is provided. Project sources should be in current dir,\nor specified with `--sourcedir`. Build directory must be provided using `--builddir`\noption. It can be a path relative to SOURCEDIR. The config is deduced automatically,\nbut the config name to use can be specified using `CONFIGNAME:` prefix to the build dir\n(e.g. `--builddir debug:/path/to/debug/build`).\n\nFiles are generated in `--outputdir`, unless a full path is provided for `NAME`.\nBy default, the `OUTPUTDIR` will be the current directory.\n\nIf `--update` option is provided, existing .vcxproj will be updated instead of\nbeing rewritten. This is useful to add a new build config to an existing project.\n\nExample:\n\n```\nvsgen project -t mylib -o vs -b build/debug -b build/release MyProject\n```\n\nwill generate `vs/MyProject.vcxproj`, with configs for debug and release,\nfor the `mylib` build target.\n\n\n### Generating solution\n\nThe `solution` command allows to generate a .sln file that includes one or many projects.\n\n`vsgen solution [--project [TARGET:]PROJECT, ...] [--projectdir PROJECTDIR] [--update] [--sourcedir SOURCEDIR] [--outputdir OUTPUTDIR] [--builddir [CONFIG:]BUILDDIR, ...] NAME`\n\nThe `NAME` is the name of the generated .sln file. It can also be a full path.\n\nThe `--project` option allows to specify the name or the path of a project to include.\nIt may be specified multiple times. If not specified, all projects from PROJECTDIR are\nincluded. `TARGET` if the name of the build target to use, if different from `PROJECT`.\nIf not specified, projects for all build targets are generated.\n\nIf specified, `PROJECTDIR` will be a sudir of `OUTPUTDIR` containing the project files.\n\nOther options are similar to those of the `project` command.\n\n\n### Using configuration file\n\nThe `generate` command allows the generation of complex solutions, using a .yaml\nconfiguration file.\n\n`vsgen generate [--sourcedir SOURCEDIR] [--outputdir OUTPUTDIR] CONFIGFILE`\n\n`CONFIGFILE` is the path to the .yaml config file. Other options are similar\nto those of `project` command.\n\n\nThe config file contains the following keys:\n\n- `outputdir`: (optional) Where to generate the solution files, if not specified\n on the command line. Default is to use current dir.\n- `projectdir`: (optional) Name of a subdirectory where to write project files.\n- `case_insensitive_targets`: (optional) If true, lower case targets match project names containing uppercase characters.\n- `only_relative_files`: (optional) If true, do not add files outside target source dir\n (i.e. where target meson.build file is located) into the project.\n- `include_from_env`: (optional) If true, will use `INCLUDE` env var for system include path.\n If 'auto', will use `INCLUDE` if it is defined.\n If false (default), will no rewrite the include path.\n This is useful when using a different build tools version that the IDE. \n- `configs`: map build directories to config names.\n- `archs`: (optional) map cpu_family to arch name. If not specified,\n use the cpu_family as the arch name.\n- `projects`: The projects to generate. See project specifications below\n for more details.\n- `solutions`: The solutions to generate. See solution specifications below\n for more details.\n\n#### Project specifications\n\nFor each project, the key is the name of the project to generate.\nIf the key is `*`, the settings apply to all unlisted projects,\nand is used as default config.\n\nIf the value is a boolean, `true` means to generate the project with default settings,\nand `false` means to not generate that project.\n\nIf the value is a map, the following keys are recognized:\n\n- `target`: the build target name. `true` means to use the project name as the target name.\n If target name begins with `dep:`, this is the name of an internal dependency object,\n used for a header only project. This project will not compile, but will display files\n from that dependency.\n `all` is used for a target that generates all targets.\n- `subdir`: if specified, put the generated project into that subdir of the project dir.\n\n#### Solution specifications\n\nFor each solution, the key is the name of the solution to generate.\n\nValue is a map with the following keys:\n\n- `projects`: A list of projects to include into the solution.\n If the value is a string, this project is included (must be listed into\n the `projects` section). If the value is a map, it map a directory name\n with a list of projects. This allow to put projects into logical directories\n in the solution. The structure is recursive. If the value is `*`, it means\n to include all projects not referenced elsewhere in the solution. If the value\n is a map with a boolean value, the key is a project name, and it is included if\n the value is `true`, and explicitly skipped if the value is `false`.\n- `build_solution`: The value is the project (or a list of projects) invoked when\n building the solution.\n- `runsettings`: (optional) If `true`, generates runsettings for all executables.\n Otherwise, map a wildcard with runsettings options. This allow special configurations\n for running tests with Google Test Adapter.\n\n## Using the API\n\n### The Generator object\n\n`vsgen` package can also be used as an API, from a python script:\n`from vsgen.api import Generator`.\n\nThe generator object takes 3 arguments:\n- `vspath`: The path where to generate the solution and project files\n (absolute, or relative to `basedir`)\n- `basedir`: (optional) The base path for other paths. Default is current dir.\n- `projectdir`: (optional) The subdir where to generate projects (relative to `vapath`)\n\nYou can also modify or override the `cpu_arch` dictionary,\nmapping cpu_family to arch name for the solution and projects.\n\nThe next step is to call `set_config`. The method takes the following arguments:\n- `builddir`: meson build dir, absolute, or relative to `self.basedir`.\n- `name`: (optional) config name to use (default is builddir name).\n- `use_include_from_env`: (optional) If `True`, will use the `INCLUDE` env var\n as system include path.\n\nThe `project` method is used to create a `VcxProj` object. Arguments are:\n- `name`: The project name.\n- `target`: (optional) The build target name. Default is project name.\n- `subdir`: (optional) Subdir (relative to projectdir) where to write the project.\n If `True`, the subdir is the project name. If `False`, no subdir is used.\n- `update`: (optional) If `True`, update existing project instead of overwriting it.\n Default is `True`.\n- `only_relative_files`: (optional) If `True`, will not reference source files that\n are not relative to the project root.\n\nThe method returns a `VcxProj` object.\n\nThe `solution` method is used to create a `SolutionFile` object.\nArguments are:\n- `name`: The solution name.\n- `update`: Whether to update existing files instead of overwriting them.\n\n### The ConfigFile object\n\nThis is a high-level interface to deal with complex solutions\nmanaged by a configuration file. See [Using configuration file] above\nfor more details about the configuration file syntax.\n\n```\nfrom vsgen.configfile import ConfigFile\nfrom pathlib import Path\n\ncf = ConfigFile('path/to/config.yaml').load() # load config file\n\nbasepath = Path('project/basepath')\noutputpath = Path('project/outputpath')\n\ncf.analyse(basepath) # analyse project introspection data\ncf.generate(basepath, outputpath, update=True) # generate project and solution files\n\n```\n\n\n### The SolutionFile object\n\nYou usually create the `SolutionFile` object using the `Generator`.\n\nNext step is to add projects to the solution:\n\n```\nsln.add_project(project, subdir, build_solution_target=False)\n```\n\n- `project` is a `VcxProj` object\n- `subdir` is an optional string if you want the project into a logical\n subdirectory in the solution.\n- `build_solution_target`: if `True`, this project is build when\n generating the whold solution. This is usually used for the `all` target only.\n\nFinally, you can write the solution file:\n\n```\nsln.write()\n```\n\n\n### The VcxProj object\n\nTo write the .vcxproj file: `prj.write()`/\n\n\n### The RunSettingsFile object\n\n[https://learn.microsoft.com/en-us/visualstudio/test/configure-unit-tests-by-using-a-dot-runsettings-file?view=vs-2022]\n\nThis allow to configure and write a runsettings file.\n\n```\nfrom vsgen.runsettings import RunSettingsFile\nfrom pathlib import Path\n\nrsfile = RunSettingsFile(Path('path/to/runsettings/file'))\nrsfile.add_solution_setting(name, value) # add a setting for whole solution\nrsfile.add_project_setting(name, value, regex) # add a setting for projects\n # matched by regex\n\nrsfile.write()\n\n```\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Generates Visual Studio solutions and projects for meson projects",
"version": "0.5.2",
"project_urls": {
"Bug Tracker": "https://gitlab.com/optelgroup-public/meson-vs-gen/-/issues",
"Homepage": "https://gitlab.com/optelgroup-public/meson-vs-gen",
"Repository": "https://gitlab.com/optelgroup-public/meson-vs-gen"
},
"split_keywords": [
"visualstudio",
"meson"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e943d2650e33598a7219917b26d727c1d272dba576783b0ff6e625c5c9d6bb1f",
"md5": "0ff6054642851a84f10b9369b44f6c83",
"sha256": "6e2a6a14f685c84d99cd9f87c6537473de0690474eb6eb6557a96327e496eed8"
},
"downloads": -1,
"filename": "meson_vs_gen-0.5.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0ff6054642851a84f10b9369b44f6c83",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4.0",
"size": 23801,
"upload_time": "2023-11-09T12:48:38",
"upload_time_iso_8601": "2023-11-09T12:48:38.866433Z",
"url": "https://files.pythonhosted.org/packages/e9/43/d2650e33598a7219917b26d727c1d272dba576783b0ff6e625c5c9d6bb1f/meson_vs_gen-0.5.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f5b489ea6096ec036ac815ced1b90662803ced4e71f8e625248ff47adbc33340",
"md5": "fa9e71acde763cf24bf65a2472c8963d",
"sha256": "e50bf54329e0b9876e167ff6a6bb6ea539f1c7e4ce380ea6b910d2540922a0d2"
},
"downloads": -1,
"filename": "meson_vs_gen-0.5.2.tar.gz",
"has_sig": false,
"md5_digest": "fa9e71acde763cf24bf65a2472c8963d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4.0",
"size": 21815,
"upload_time": "2023-11-09T12:48:40",
"upload_time_iso_8601": "2023-11-09T12:48:40.315675Z",
"url": "https://files.pythonhosted.org/packages/f5/b4/89ea6096ec036ac815ced1b90662803ced4e71f8e625248ff47adbc33340/meson_vs_gen-0.5.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-09 12:48:40",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "optelgroup-public",
"gitlab_project": "meson-vs-gen",
"lcname": "meson-vs-gen"
}
JSON