Please install all necessary prerequisites on your system.
For detailed instructions for a Windows machine, follow this guide.
yarn
This will build and start CrossModel as a web application. When the web application is running you can open http://localhost:3000 in your browser to use CrossModel.
yarn build:browser &&
yarn start:browser
This will build and start CrossModel as a native desktop application for the OS (Windows, Linux or MacOS) where the command is started.
yarn build:electron &&
yarn start:electron
Under examples/verdaccio-example/workspace we provide an example workspace with some demo packages containing entities, relationships and system diagrams.
Each package represents a dedicated system or library and may depend on other packages.
Using a known package structure - npm in our case - we can re-use large parts of the package management to download dependencies that are not locally available from an external package registry. In order to test this behavior, we use verdaccio as a local npm registry that provides some models that are needed by our workspace packages. You can start verdaccio using
yarn start:verdaccio
The local npm registry will be available under http://localhost:4873/ where we already provide four packages by default.
After opening the workspace, you can install the necessary dependencies in the example workspace by opening a terminal in examples/verdaccio-example/workspace and execute
npm install
This should download all dependencies into dedicated node_modules directories within the workspace.
Currently there is still an issue where new files are not recognized automatically, so you need to reload your workspace once for all the dependencies to be properly recognized.
Start watching all packages of your application for either browser or electron version.
yarn watch:browser
or
yarn watch:electron
or watch only specific packages with
cd packages/<package-name>
yarn watch
and the Electron example.
cd applications/electron-app
yarn watch
Run the example as described above.
Any code changes will be automatically detected and the application will be re-compiled.
If you only made changes to the frontend or plugins, simply reloading the running application with F5 is enough.
If you also made changes to the backend, you can close and restart the application without manual re-compilation.
You can work on CrossModel from within a Dev Container. The best way to do so is create a new Dev Container and cloning the repository in there. For instructions please consult this page.
Short steps:
- Install Docker with WSL 2 engine enabled.
- In VS Code press [CTRL] + [SHIFT] + [P] and type 'Dev Container: Clone Repository in Container Volume...' and press [Enter].
- Enter the current repository URL and press [Enter]. Now the dev container will be created with the Git repository cloned in it (faster then cloned locally in Windows).
We package CrossModel either for the browser (Docker) or desktop application (Electron).
To package the web application we build a docker image. There are currently two Dockerfile definitions, one based on Alpine Linux and one based on Debian. Some users might prefer Debian over Alpine as based, which is why we have both options.
To create the Alpine based image, execute the following command:
docker build -t crossmodel:0.0.0-alpine -f .\Dockerfile .
To create the Debian based image, execute the following command:
docker build -t crossmodel:0.0.0-debian -f .\Dockerfile.debian .
In the main build action we build and publish the Alpine version.
To package CrossModel as a desktop application, execute the following command:
yarn theia:electron package
Depending on the platform, this will produce an executable or an installer for the application under applications/electron-app/dist.
Details about the packaging can be configured in applications/electron-app/electron-builder.yml.
A general overview of the application architecture is provided in the Architecture Overview. The repository itself contains the following components structured as follows:
├── applications
│ ├── browser-app # Browser application
│ └── electron-app # Electron application
├── configs
├── docs # Documentation
├── examples
│ ├── libraries # Example libraries referenced in the local npm registry
│ ├── registry # Local npm registry using Verdaccio
│ └── workspace # Workspace that can be opened in the tool
├── extensions # VS Code extensions
│ └── crossmodel-lang # CrossModel language support (through three servers)
│ └── src
│ ├── glsp-server # Graphical modelling server based on GLSP
│ ├── language-server # Textual modelling server based on Langium
│ ├── model-server # Custom model server to provide access to the semantic models
│ ├── extension.ts # Extension starting the server process and the language client
│ └── main.ts # Server process starting up all servers
└── packages # Theia extensions
├── core # Core customizations
├── form-client # Form editor widget connecting to the model server
├── glsp-client # Diagram configuration and widget using the GLSP server
└── product # Application-level modifications
- mui-x : MUI X is open core—base components are MIT-licensed, while more advanced features require a Pro or Premium commercial license. We are currently only using core-base
- react-tabs: MIT
- chevrotain: This library is a dependency of langium. To get the Yaml language working in crossmodel an example implementation of the python language of chevrotain has been used. This example has been modified to make it work for the yaml language.