tmbuild's core idea in our blog-post One-button source code builds.
tmbuild is our custom one-click "build system." and it is quite a powerful tool. It allows you to do the most important tasks when developing with The Machinery: Building your plugin or the whole engine.
You can execute the tool from any terminal such as PowerShell or the VS Code internal Console window.
The key features are:
- cleaning the solution/folder
- downloading all the dependencies
- running our unit tests
This walkthrough introduces you to
tmbuild and shows you how to use and manipulate The Machinery Projects. You will learn about:
- How to build with it
- How to build a specific project with it
- How to package your project
Also, you will learn some more advanced topics such as:
- How to build/manipulate tmbuild
Table of Content
- Installing tmbuild
- Set up our environment variables
- Let us Build a plugin.
- Let us build a specific project.
- How how to package a project via tmbuild?
- How to build or manipulate tmbuild from source
- How to add tmbuild globally accessible?
Alternatively, you can build it from source
code\utils.We will talk about this later in this walkthrough.
Before we use tmbuild, we need to ensure that we have installed either build-essentials under Linux, XCode on Mac, or Visual Studio 2017 or 2019 (Either the Editor such as the Community Edition or the Build Tools).
Windows Side nodes:
On Windows, it is essential to install the C/C++ Build tools.
If you run into the issue that tmbuild cannot find Visual Studios 2019 on Windows, it could be because you installed it on a typical path. No problem, you can just set the environment variable
TM_VS2019_DIR to the root
C:\Program Files (x86)\Microsoft Visual Studio\2019. The tool will find the right installed version automagically.
Before we can build any project, we need to set up our environment. You need to set the following environment variable: (If this one has not been set the tool will not be able to build)
TM_SDK_DIR- This is the path to find the folder
headersand the folder
If the following variable is not set, the tool will assume that you intend to use the current working directory:
TM_LIB_DIR- The folder which determines where to download and install all dependencies (besides the build environments)
How to add environment variables?
On Windows all you need to do is you need to add the folder where you installed The Machinery to your environment variables. You can do this like this:
Start > Edit the system environment variables > environment variables > system variables > click New... > add
TM_LIB_DIR as the Variable Name and the needed path as the Variable Value.
Close and restart the terminal or Visual Studio / Visual Studio Code.
As an alternative, you can set an environment variable via PowerShell before you execute tmbuild, which will stay alive till the end of the session:
You open the terminal or edit with your favorite text editor
~/.bashrc and you add the following lines:
#... export TM_SDK_DIR=path/to/themachinery/ export TM_LIB_DIR=path/to/themachinery/libs
(e.g. via nano nano
All you need to do is: navigate to the root folder of your plugin and run in PowerShell
If you have not added tmbuild.exe to your global PATH, you need to have the right path to where tmbuild is located.
[email protected]/home/user/tm/plugins/my_plugin/> ./../../bin/tmbuild
This command does all the magic. tmbuild will automatically download all the needed dependencies etc., for you (Either in the location set in
TM_LIB_DIR or in the current working directory).
You may have noticed tmbuild will always run unit tests at the end of your build process.
Note: tmbuild will only build something when there is a premake5.lua and a libs.json in the current working directory.
Imagine you have been busy and written a bunch of plugins, and they are all connected and managed via the same Lua file (premake5 file).
Now you do not want to check everything all the time. No problem, you can follow these steps:
If you run
tmbuild --help/-h, you will see many options. One of those options is
--project. This one allows you to build a specific project.
tmbuild.exe --project my-project-name
The tool will automatically find the right project and build it. On Windows, you can also provide the relative/absolute path to the project with extension: ``
tmbuild --project /path/to/project.vcxproj
Note: If a project cannot be found it will build all projects.
To package a project via tmbuild, all you need to do is use the
-p [package name] or
--package [package name] command. A package file needs to be of type
.json and follow our package scheme, which you can find here.
You can find the source code of tmbuild in the folder
code\utils\tmbuild. In the folder
code\utils, you can also find the source code of all the other uses the engine uses.
You can build tmbuild via tmbuild. All you need to do is navigate the
code\utils folder and run
tmbuild --project tmbuild.
If you do not have access to a build version of tmbuild but to the whole source, you have to follow the following steps:
Make sure you have Visual Studio 19 and the Build Tools installed. Besides, check if you can find
msbuild in the terminal. You can install
msbuild / vs studio via PowerShell: https://github.com/Microsoft/vssetup.powershell
To check just run:
if you cannot find it just add it to your environment path variables: with e.g.
C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\MSBuild\Current\Bin\
To build from source:
Open a PowerShell instance in The Machinery folder and run the following commands:
# this part can be skipped if you have already downloaded # all the dependencies and created a highlevel folder to your lib dependencies: mkdir lib cd lib wget https://ourmachinery.com/lib/bearssl-0.6-r1-win64.zip -OutFile bearssl-0.6-r1-win64.zip wget https://ourmachinery.com/lib/premake-5.0.0-alpha14-windows.zip -OutFile premake-5.0.0-alpha14-windows.zip Expand-Archive -LiteralPath './bearssl-0.6-r1-win64.zip' -DestinationPath "." Expand-Archive -LiteralPath './premake-5.0.0-alpha14-windows.zip' -DestinationPath "." cd .. # continue here if the dependencies are already downloaded # set TM_LIB_DIR if you have not set it already $env:TM_LIB_DIR="/path/to/themachinery/lib" $env:TM_SDK_DIR="/path/to/themachinery/" # run premake ./../../lib/premake-5.0.0-alpha14-windows/premake5 [vs2019|vs2017] # navigate to the highlevel folder of the code (here you find the libs.json and the # premake5.lua cd code/utils msbuild.exe "build/tmbuild/tmbuild.vcxproj" /p:Configuration="Debug Win64" /p:Platform=x64
Make sure that you either choose vs2019 or vs2017 not [vs2019|vs2017]
Open a terminal instance and run the following commands:
# If you do not have the huild essentials installed make sure you do: sudo apt install build-essential clang zip -y # otherweise continue here: cd your-folder-of-tm # this part can be skiped if you have already downloaded # all the dependencies and created a highlevel folder to your lib dependencies: mkdir lib cd ./lib wget https://ourmachinery.com/lib/bearssl-0.6-r1-linux.zip wget https://ourmachinery.com/lib/premake-5.0.0-alpha15-linux.zip unzuip bearssl-0.6-r1-linux.zip . unzip premake-5.0.0-alpha15-linux.zip . chmod +x ./premake-5.0.0-alpha15-linux/premake5 cd .. # continue here if the dependencies are already downloaded # set TM_LIB_DIR if you have not set it already export TM_LIB_DIR=/path/to/themachinery/lib export TM_SDK_DIR=/path/to/themachinery/ # run premake ./../../lib/premake-5.0.0-alpha15-linux/premake5 gmake # navigate to the highlevel folder of the code (here you find the libs.json and the # premake5.lua cd code/utils # run make: make tmbuild
On Windows, all you need to do is you need to add the folder/bin to your environment variables. This can be done like this:
Start > Edit the system environment variables > environment variables > system variables > search in the list for path > click Edit > click new > add the absolute path to
themachinery/bin in there
re-login or reboot.
You open the terminal or edit with your favorite text editor
~/.bashrc, and you add the following lines:
(e.g. via nano nano