Welcome to CMake Converter’s documentation¶
Documentation Content:
Introduction¶
About CMake Converter¶
CMake Converter is an open source software written in Python under the terms of the GNU Affero General Public License .
This application is for developers and integrators who want to automate the creation of CMakeLists.txt
for their build systems from Visual Studio solution files.
Features¶
CMake Converter converts your *.sln
file (vcxproj
and vfproj
are supported only) into corresponding tree of CMakeLists.txt
.
It tries to translate data such as compile and link flags, project files, project dependencies, outputs of the produced binaries and more into CMake language.
Release cycle¶
CMake Converter has no strict schedule for releasing.
Other features will come in the next versions and you can propose new features through project issues. Each feature is discussed in a separate issue.
Install CMake Converter¶
Requirements¶
You must have Python 3 installed to make this library work.
Note: CMake Converter is not compatible with Python 2 !
Installation (from Pip)¶
You can install cmake-converter as a standard python library, with pip
:
pip install cmake_converter
Install last pre-release or development version of cmake-converter:
pip install --pre cmake_converter
Installation (from Sources)¶
Clone and install¶
To install from sources, you’ve to clone this repository and make a pip install:
git clone https://github.com/algorys/cmakeconverter.git
cd cmakeconverter
pip install .
External Libraries¶
You need to install Python modules that are listed in requirements.txt
file with pip:
colorama
lxml
Use CMake Converter¶
Quick Use¶
To use cmake converter, simply give your *.sln
file to cmake-converter command:
cmake-converter -s <path/to/file.sln>
Advance Usage¶
The cmake-converter
command accepts a lot of parameters to try to suit the majority of situations.
Main¶
Manage script arguments and launch
Solution Conversion¶
With cmake-converter, you can convert full Visual Studio solutions.
The script will extract data from all supported *proj files and create the corresponding CMakeLists.txt.
With the following project structure:
project/
└── msvc
├── libone
│ └── libone.vcxproj
├── libtwo
│ └── libtwo.vcxproj
└── myexec
├── myexec.sln
└── myexec.vcxproj
Then you’ll run cmake-converter as follow:
cmake-converter \
--solution=project/msvc/myexec/myexec.sln \
--verbose-mode \
--private-include-directories \
--warning-level=3
And you’ll have the following CMakeLists.txt generated:
project/
└── msvc
├── libone
│ ├── CMakeLists.txt *
│ └── libone.vcxproj
├── libtwo
│ ├── CMakeLists.txt *
│ └── libtwo.vcxproj
└── myexec
│
└── CMake *
│ ├── Default*.cmake *
│ └── Utils.cmake *
├── CMakeLists.txt *
├── myexec.sln
└── myexec.vcxproj
Hints¶
You can add CMake/GlobalSettingsInclude.cmake file for global custom CMake settings.
Pay attention on warnings and do proposed fixes.
Run cmake-converter –help for more info.
Generated CMakeLists.txt¶
All CMakeLists.txt generated by cmake-converter follow the same hierarchy. If you converted a solution, each converted directory with *proj file will have its own file.
In order to facilitate their understanding, the generated files are organized by “section”. Here is a description for each of them. Actually each section at generated scripts is separated with comment and can be read well.
Root of CMake tree¶
After conversion the root of CMake tree appears beside *.sln file. So, give the path of the root CMakeLists.txt to cmake to parse all converted tree. Root CMakeLists.txt contains info about:
1. Architectures used in solution.
2. Solution configutation names.
3. Windows SDK version used.
4. Sets cmake minimum required version.
5. Includes optional GlobalSettingsInclude.cmake
6. Adds all converted subdirectories with projects.
Top of file (project)¶
Creating of corresponding Visual Studio project with used languages.
Files & Targets¶
Files (source groups)¶
Converter will collect all your source files and add them to the corresponding target. The files will be added according source groups and sorted alphabetically.
IMPORTANT: names of source groups must be without special symbols (only CMake like variable). Spaces are accepted.
Library & Executable (target)¶
After script get all information, he create your library (STATIC or SHARED) or your executable. Also here may be used add_precompiled_header if PCH is turned on.
Property files (*.props)¶
Converter does not support translation of property. It addes links to correspondent files at the same location. Example: if we have following link at source xml:
f1/f2/my-settings.props
You’ll get usage of similar cmake file that should be created manually:
use_props(${PROJECT_NAME} “${CMAKE_CONFIGURATION_TYPES}” “f1/f2/my-settings.cmake”)
In case of absence of cmake file CMake will throw warning:
Corresponding cmake file from props <cmake-file-name> doesn’t exist
Include directories¶
Adds include directories from corresponding visual studio project. Includes are PUBLIC by default. But you may use –private-include-directories to make them private and make your solution smarter.
Compile definitions¶
Adds compile definitions from corresponding visual studio project.
Compile and link options¶
The biggest part of the work done by CMake Converter. CMake-converter will add flags for each $<CONFIG>
.
Only MSVC and ifort compilers are supported. Flags applied with target_compile_options and target_link_options.
Linux¶
On Linux only translation of ifort options is supported.
Windows¶
MSVC and ifort options are supported.
Dependencies¶
Dependencies are binaries you have set in “Additional Dependencies” of your *proj project, like shared or static libraries or references to other solution projects.
add_dependencies
command contains corresponding references.
target_link_libraries
command contains references that need to link and other external dependencies.
target_link_directories
may be used here as well.
Also cmake converter tries to read info about used NuGet packages and makes stubs for using it with use_package
function.
Use CMake¶
CMake Converter try to take as much information as possible from your *proj file. However, it’s recommended to read and test the generated CMakeLists.txt before using it in production !
Once CMake Converter has generated a CMakeLists.txt file, to compile with CMake, type the following commands:
# Go to CMake tree root (not necessary, may be relative):
cd path/to/Root/of/CMake/tree
# Generate the "Makefile"
cmake -S . -B build
# Launch compilation
cmake --build build
You can also provide a specific Generator with -G "<GENERATOR_NAME>"
. Please refer to CMake Generator Documentation.
You can provide the build type by add -DCMAKE_BUILD_TYPE=<BUILD_TYPE>
.
CMake provides a lot of other options that you can discover in their official documentation.
API Documentation¶
DataConverter¶
Manage conversion of data into CMake
-
class
cmake_converter.data_converter.
DataConverter
¶ Bases:
object
Base class for converters
-
static
collect_data
(context)¶ Collect data for converter.
-
convert_project
(context, xml_project_path, cmake_lists_destination_path)¶ Method template for data collecting and writing
-
static
copy_cmake_utils
(cmake_lists_path)¶ Copy necessary util files into CMake folder
-
do_conversion
(project_context, input_data_for_converter)¶ Executes conversion with given projects input data
-
merge_data_settings
(context)¶ Merge common settings found among configuration settings (reduce copy-paste)
Parameters: context – Returns:
-
run_conversion
(subdirectory_targets_data)¶ Routine that converts projects located at the same directory
-
verify_data
(context)¶ Verify procedure after gathering information from source project
-
static
Context object descriptor¶
-
class
cmake_converter.context.
Context
¶ Bases:
object
Converter context
-
clone
()¶ Deep clone of Context
Returns:
-
static
get_project_initialization_dict
()¶ Get initializer functors mapped to path keys
-
init
(source_project_path, cmake_lists_destination_dir)¶ Initialize instance of Context with Initializer
Parameters: - source_project_path –
- cmake_lists_destination_dir –
Returns:
-
Data Files¶
Manage the VS Project data and creation of CMakeLists.txt file
-
cmake_converter.data_files.
get_cmake_lists
(context, cmake_path=None, open_type='w')¶ Create CMakeLists.txt file in wanted “cmake_path”
Parameters: Returns: cmake file wrapper opened
Return type: _io.TextIOWrapper
-
cmake_converter.data_files.
get_definitiongroup
(target_platform)¶ Return ItemDefinitionGroup namespace depends on platform and target
Parameters: target_platform (tuple[str,str]) – wanted target: debug | release Returns: wanted ItemDefinitionGroup namespace Return type: str
-
cmake_converter.data_files.
get_propertygroup
(target_platform, attributes='')¶ Return “property_groups” value for wanted platform and target
Parameters: Returns: “property_groups” value
Return type:
-
cmake_converter.data_files.
get_vcxproj_data
(context, vs_project)¶ Return xml data from “vcxproj” file
Parameters: Returns: dict with VS Project data
Return type:
-
cmake_converter.data_files.
get_xml_data
(context, xml_file)¶ Return xml data from “xml” file
Parameters: Returns: dict with VS Project data
Return type:
-
cmake_converter.data_files.
search_file_path
(context, xml_file)¶ Util function for checking file in path.
Dependencies¶
Manage directories and libraries of project dependencies
-
class
cmake_converter.dependencies.
Dependencies
¶ Bases:
object
Class who find and write dependencies of project, additional directories…
-
static
get_dependency_target_name
(context, vs_project)¶ Return dependency target name
Parameters: Returns: target name
Return type:
-
static
set_additional_include_directories
(aid_text, setting, context)¶ Return additional include directories of given context
Parameters: Returns: include directories of context, separated by semicolons
Return type:
-
static
set_target_additional_dependencies_impl
(context, dependencies_text, splitter)¶ Implementation of Handler for additional link dependencies
-
static
Flags¶
Manage compilation flags of project
ProjectFiles¶
Manages the recovery of project files
-
class
cmake_converter.project_files.
ProjectFiles
¶ Bases:
object
Class that collects and store project files
-
add_file_from_node
(context, **kwargs)¶ Adds file into source group and creates file context using into from xml node
-
apply_files_to_context
(context)¶ Analyzes collected set of files and initializes necessary variables
-
find_cmake_target_languages
(context)¶ Add CMake Project
-
include_directive_case_check
(context, file_path_name, file_lists_for_include_paths)¶ Dummy to fix crash
-
init_file_lists_for_include_paths
(context)¶ For include directive case ad path checking. Works only with vfproj. :param context: :return:
-
ProjectVariables¶
Manage creation of CMake variables that will be used during compilation
-
class
cmake_converter.project_variables.
ProjectVariables
¶ Bases:
object
Class that manages project variables
-
static
set_output_dir_impl
(context, output_node_text)¶ Parameters: - context –
- output_node_text –
Returns:
-
static
set_output_file_impl
(context, output_file_node_text)¶ Common routine for evaluating path and name of output file
-
static
set_path_and_name_from_node
(context, node_name, file_path, path_property, name_property)¶ Common routine for evaluating path and name from node text
-
static
set_target_name
(context, target_name_value)¶ Evaluates target name and sets it into project context
-
static
Utils¶
Utils manage function needed by converter
-
class
cmake_converter.utils.
Utils
¶ Bases:
object
Basic Class for holding util functions needed by converter
-
init_context_current_setting
(context)¶ Define settings of converter.
Parameters: context (Context) – converter context
-
static
lists_of_settings_to_merge
()¶ Lists of keys of settings at context that will be merged
-
-
cmake_converter.utils.
check_for_relative_in_path
(context, path, remove_relative=True)¶ Return path by adding CMake variable or current path prefix, to remove relative
Parameters: Returns: formatted path without relative
Return type:
-
cmake_converter.utils.
cleaning_output
(context, output)¶ Clean Output string by remove VS Project Variables
Parameters: Returns: clean output
Return type:
-
cmake_converter.utils.
escape_string
(context, wrong_chars_regex, input_str)¶ Removes wrong chars from input string
-
cmake_converter.utils.
get_actual_filename
(context, name)¶ Return actual filename from given name if file iis found, else return None
Parameters: Returns: None | str
Return type: None | str
-
cmake_converter.utils.
get_dir_name_with_vars
(context, path)¶ Tries to split directory and filename from given path
-
cmake_converter.utils.
get_global_project_name_from_vcxproj_file
(vcxproj)¶ Return global project name from “.vcxproj” file
Parameters: vcxproj (dict) – vcxproj data Returns: project name Return type: str
-
cmake_converter.utils.
get_mapped_architectures
(sln_setting_2_project_setting, arch)¶ Get all projects architectures that mapped onto given solution one
-
cmake_converter.utils.
get_mount_point
(path)¶ Returns mount point of given path
-
cmake_converter.utils.
init_colorama
()¶ Initialization of colorful console output
-
cmake_converter.utils.
insensitive_glob
(path)¶ Searches given path case insensitive
-
cmake_converter.utils.
is_settings_has_data
(sln_configurations_map, settings, settings_key, sln_arch=None, conf=None)¶ Checker of available settings in context
-
cmake_converter.utils.
make_cmake_configuration
(context, sln_configuration)¶ Tries to make cmake configuration name from sln_configuration
-
cmake_converter.utils.
make_cmake_literal
(context, input_str)¶ Tries to make cmake literal from input string
-
cmake_converter.utils.
make_os_specific_shell_path
(output)¶ Tries to make path readable with CMake
-
cmake_converter.utils.
message
(context, text, status)¶ Displays a message while the script is running
Parameters:
-
cmake_converter.utils.
normalize_path
(context, working_path, path_to_normalize, remove_relative=True, unix_slash=True)¶ Normalize path from working path
Parameters: Returns: normalized path
Return type:
-
cmake_converter.utils.
prepare_build_event_cmd_line_for_cmake
(context, build_event)¶ Tries to fit build event command to be compliant CMake language
-
cmake_converter.utils.
replace_vs_var_with_cmake_var
(context, var)¶ Translate Visual studio variable into CMake variable
-
cmake_converter.utils.
replace_vs_vars_with_cmake_vars
(context, output)¶ Translates variables at given string to corresponding CMake ones
-
cmake_converter.utils.
resolve_path_variables_of_vs
(context, path_with_vars)¶ Evaluates paths with visual studio variables
-
cmake_converter.utils.
set_native_slash
(raw_path)¶ Set native slash
Parameters: raw_path (str) – any style path Returns: unix style path Return type: str
-
cmake_converter.utils.
set_unix_slash
(win_path)¶ Set windows path to unix style path
Parameters: win_path (str) – windows style path Returns: unix style path Return type: str
-
cmake_converter.utils.
take_name_from_list_case_ignore
(context, search_list, name_to_search)¶ Return real name of name to search
Parameters: Returns: real name
Return type: