Installation
MARS-Curiosity can be installed with the executable installer (recommended), with TMS Smart Setup, or manually from sources.
Option 1 — Executable installer
The fastest way to get started:
- Download the setup from the latest release page.
- Run it. The installer configures the library paths and installs the design-time packages for your RAD Studio version.
Keep your projects out of the MARS folder
Uninstalling MARS, which the setup also does before installing a new version, deletes the content of the MARS folder. Since 1.8.1 the uninstaller leaves alone the folders of Demos that are not demos shipped with MARS, and the setup moves the ones it finds in the Demos folder of the previous version to Documents\MARS Projects before uninstalling it (older uninstallers delete the whole Demos folder). Anyway, create your projects somewhere else: MARSCmd proposes Documents\MARS Projects.
Option 2 — TMS Smart Setup
TMS Smart Setup is a free, open-source command-line tool that downloads, builds and registers Delphi libraries. MARS ships a tmsbuild.yaml, so Smart Setup can build it from sources for every supported Delphi version installed on your machine (10.4 Sydney and newer, Win32/Win64).
Download and install Smart Setup (version 3.5 or later).
The community server, where open-source libraries are listed, is disabled by default. Enable it once:
bashtms server-enable community trueInstall MARS:
bashtms install andreamagni.mars
Smart Setup clones the repository, compiles the runtime and design-time packages (Debug and Release), installs the design-time packages in the IDE and adds the MARS source folders to the library path. Later on, tms update andreamagni.mars gets the latest version and rebuilds it, and tms uninstall andreamagni.mars removes it.
The JOSE JWT backend (MARS.JOSE package) uses the delphi-jose-jwt library, which Smart Setup installs as a product of its own: MARS.JOSE is built only when it is installed. The mORMot backend, the default on Windows, needs nothing else. To use JOSE:
tms install paolo-rossi.delphi-jose-jwtInstalling it after MARS is fine: Smart Setup rebuilds MARS and adds MARS.JOSE.
WARNING
Use one installation method only. If MARS is already installed with the executable installer or manually, remove it first, so the IDE doesn't load two copies of the same packages.
The packages of the Devart integrations (MARS.UniDAC, MARS.MyDAC, MARS.IBDAC and the client ones, MARSClient.UniDAC, MARSClient.MyDAC, MARSClient.IBDAC with their …Design packages) are not built by Smart Setup, because they require Devart UniDAC, MyDAC and IBDAC: if you need them, enable MARS_UNIDAC, MARS_MYDAC or MARS_IBDAC in Source\MARS.inc and build them manually from the Packages folder. The executable installer builds them when the Devart library is installed. See Data Access.
The test projects (the ...Tests project of an application created with MARSCmd, MARS.Tests) also need Delphi-Mocks, which is not a Smart Setup product: clone it and add its Source folder to the library path.
Option 3 — Manual installation
Get a copy of MARS with
git clone, including its submodules (delphi-jose-jwt, used by the JOSE JWT backend, and Delphi-Mocks, used by the test projects; the other third-party libraries are part of the repository):bashgit clone --recurse-submodules https://github.com/andrea-magni/MARS.gitIn a clone made without
--recurse-submodules, rungit submodule update --init. The Download ZIP button of GitHub leavesThirdParty\delphi-jose-jwtandThirdParty\Delphi-Mocksempty: download them at the versions shown inThirdParty/README.mdand extract them there.Add the following folders to your RAD Studio Library Path (Tools ▸ Options ▸ Language ▸ Delphi ▸ Library):
[MARS Folder]\Source[MARS Folder]\ThirdParty\delphi-jose-jwt\Source\Common[MARS Folder]\ThirdParty\delphi-jose-jwt\Source\JOSE[MARS Folder]\ThirdParty\mORMot2\src\core[MARS Folder]\ThirdParty\mORMot2\src\crypt[MARS Folder]\ThirdParty\mORMot2\src\lib[MARS Folder]\ThirdParty\Neslib.Yaml[MARS Folder]\ThirdParty\Neslib.Yaml\Neslib[MARS Folder]\ThirdParty\Delphi-Mocks\Source(test projects:MARS.Tests, the...Testsproject of a new application)
Build the runtime/design-time packages. For example, on 13 Florence:
- Open
[MARS Folder]\Packages\13Florence\MARS.groupproj- Build All (it also builds the
JOSEpackage of delphi-jose-jwt, required byMARS.JOSE)
- Build All (it also builds the
- Open
[MARS Folder]\Packages\13Florence\MARSClient.groupproj- Build All
- Install
MARSClient.CoreDesign - Install
MARSClient.FireDACDesign - with a Devart library and its define enabled in
MARS.inc: buildMARSClient.UniDAC,MARSClient.MyDACorMARSClient.IBDACand install the corresponding…Designpackage (the server packages,MARS.UniDAC,MARS.MyDAC,MARS.IBDAC, are inMARS.groupproj)
Adjust the package folder to match your Delphi version.
- Open
Compatibility
MARS supports Delphi 10.4 Sydney up to 13 Florence. Earlier versions are not supported: compiling MARS with them stops with an explicit error.
Bootstrap a new project with MARSCmd
MARS ships a small utility (with a user interface, and a command line version) that scaffolds a complete, ready-to-run project for you from a template:
MARSTemplate: Indy, endpoints as resource classes;MARSTemplateDCS: Delphi Cross Socket, endpoints as resource classes;MARSTemplateRoutes: Indy, endpoints as routes defined in code (Express style).
- Compile and run
MARScmd_VCL.dprojin[MARS Folder]\Utils\Source\MARScmd. - Follow the prompts. Choose the template on the first page: MARSCmd lists the
Demos\MARSTemplate*folders (...picks a template from another folder). It clones the template into a new folder with your chosen project name, giving you a server (console / VCL / FMX / service / ISAPI / Apache / daemon variants), a client, and a test project. The.inifiles of the new project get a freshly generated randomJWT.Secret.
The settings of the new project are in bin\Server.ini, shared by all its server flavors (console, VCL, FMX, service, daemon, ISAPI, Apache, FastCGI): each flavor has its own small .ini, named after the executable, that includes Server.ini with an [Include] section and can override any value (i.e. a different Port). The generated JWT.Secret is in Server.ini.
The new project goes to Documents\MARS Projects\<project name> by default; next time MARSCmd proposes the folder used last (saved in %APPDATA%\MARS-Curiosity\MARSCmd.ini; a saved folder that no longer exists, or that is inside the MARS folder or the temp folder, is ignored). A destination inside the MARS folder asks for confirmation, as uninstalling or upgrading MARS would delete it, and an existing folder that is not empty is never overwritten.
To start from an OpenAPI document instead, MARSgen creates the project from the same templates with the resources of the document already in it (MARSgen openapi <document> --project <Name>).
The template refers to the MARS folder with relative paths (..\..\Source). Outside the MARS folder, MARSCmd writes them as $(MARSDIR)\Source, $(MARSDIR)\ThirdParty\...: MARSDIR is the IDE environment variable set by the setup to the MARS folder (Tools ▸ Options ▸ IDE ▸ Environment Variables). With TMS Smart Setup or a manual installation, define it yourself or rely on the library path.
From the command line
MARScmd.exe ([MARS Folder]\Utils\Bin\Win32, project MARScmd.dproj in the same source folder) does the same without a user interface, for scripts and automation:
MARScmd CustomersServer --template MARSTemplateRoutes --dest C:\Projects\CustomersServer| Option | Default | Meaning |
|---|---|---|
<ProjectName> | The name of the project (a Delphi identifier): it replaces MARSTemplate in the names and contents of the files. | |
--template <name or folder> | MARSTemplate | A folder of Demos (MARScmd --list-templates lists them) or the path of a template. |
--dest <folder> | <projects folder>\<ProjectName> | The folder of the new project: it must not exist, or be empty. The projects folder is the one proposed by MARSCmd (see above); the command line does not change it. |
--allow-inside | Allows a destination inside the MARS folder (otherwise refused, as uninstalling or upgrading MARS deletes it). | |
--search <text> | MARSTemplate | The text replaced by the project name. |
--matches <patterns> | *.pas|*.dpr|*.dproj|*.dfm|*.xfm|*.groupproj|*.deployproj | The files whose content is changed, separated by |. |
--mars <folder> | the folder of MARScmd.exe | The MARS folder (with the Demos of the templates). |
MARScmd --help prints the usage. The exit code is 0 when the project is created, 1 on errors (i.e. a destination that is not empty), 2 on a wrong command line.
This is the recommended way to start a brand-new MARS application — see Your First Server for a walkthrough of what the generated code does.
Project structure
After installation, the repository layout is:
| Folder | Contents |
|---|---|
Source | The MARS library units (server + client). |
Packages | RAD Studio packages, one subfolder per Delphi version. |
Demos | Ready-to-run sample projects (see Demos). |
Utils | Tools, including the MARSCmd project bootstrapper (MARScmd_VCL.exe and MARScmd.exe, the command line version). |
ThirdParty | Bundled dependencies (Delphi-Cross-Socket, JOSE-JWT, mORMot, Neslib.Yaml, Delphi-Mocks): origin, version and license of each in ThirdParty/README.md. |
tests | DUnitX test suite. |
