chore: prep for publish

Author: elkoDev

README.md

@@ -1,20 +1,26 @@
-# bcs-engineering-dsl
+# BCS Engineering Framework
 
-## 1. Prerequisites
+## 1 Prerequisites
 
 - Windows with TcXaeShell Version 15.0 or higher
 
-## 2. Example
+## 2 Installation and Usage
 
-To run the example in the folder [language/example](language/example), you need to follow the following steps.
+To install the complete framework, you need to install three components:
 
-### 2.1 Generate the artifacts
+1. VS Code extension: `BCS Engineering DSL`
+2. `bcs-engineering-cli` - The CLI to generate the artifacts from the DSL files.
+3. `TcAutomation` - The tool to create and deploy the TwinCAT project from the generated artifacts.
 
-For this follow the installation instructions in the [bcs-engineering-dsl](language/README.md) README file.
+After the installation you can have a look at the [example](language/example) folder to see how to use the framework.
+
+### 2.1 Install bcs-engineering-cli and VS Code Extension
+
+To install the `bcs-engineering-cli` and `BCS Engineering DSL` VS Code extension, follow the installation and usage instructions in the [README](language/README.md) file.
 
 ### 2.2 Install TcAutomation
 
-_TcAutomation_ is responsible for the creation of the corresponding TwinCAT project given the generated artifacts. To install it, you need to run the `TcAutomationInstaller.exe`.
+_TcAutomation_ is responsible for the creation and deployment of the corresponding TwinCAT project given the generated artifacts. To install it, you need to run the `TcAutomationInstaller.exe`.
 To create the installer, follow the steps described in the [TcAutomation](TcAutomation/README.md) README file.
 
 ### 2.3 Check TcAutomation Installation

TcAutomation/README.md

@@ -1,16 +1,17 @@
-# Build
+# TcAutomation Deployment Tool
+
+## 1 Prerequisites
+
+- [Inno Setup](https://jrsoftware.org/isinfo.php)
+
+## 2 Build Project
 
 ```bash
 msbuild /p:Configuration=Release TcAutomation.csproj
 ```
 
-# Windows Installer
-
-## Pre-requisites
-- Build the project in Release mode.
-- [Inno Setup](https://jrsoftware.org/isinfo.php)
+## 3 Create Installer
 
-## Build
-- Open the `TcAutomation.iss` file in Inno Setup.
+- Open the [TcAutomationInstaller.iss](TcAutomationInstaller.iss) file within the Inno Setup.
 - Click the "Build/Compile" button (or press Ctrl+F9)."
-- The installer will be created in the `output` folder.
+- The installer will be created in the [output](output) folder.

language/README.md

@@ -1,35 +1,44 @@
 [![CI](https://github.com/elkoDev/bcs-engineering-dsl/actions/workflows/ci.yml/badge.svg)](https://github.com/elkoDev/bcs-engineering-dsl/actions/workflows/ci.yml)
 
-# 1. Setup
+# BCS Engineering DSL
 
-## 1.1 Install Dependencies
+## 1 Publishing
+
+### 1.1 Install Dependencies
 
 ```bash
 npm install
 ```
 
-## 1.2 Build
+### 1.2 Build
 
 ```bash
 npm run langium:generate && npm run build
 ```
 
-## 1.3 Generate Extension
+### 1.3 Generate Extension
 
 Before generating the extension, make sure to run the build commands first.
 
 ```bash
 vsce package
 ```
 
-## 1.4 Publish CLI
+### 1.4 Publish CLI
+NOTE: Previous versions have been published under the name `bcs-engineering-dsl` on my personal npm account. To avoid confusion, you might want to publish under a different name.
 
 ```bash
 npm login
 npm publish --access public
 ```
 
-## 1.5 Install CLI
+## 2 Installation
+
+### 2.1 Install VS Code Extension
+
+Right click on the `bcs-engineering-dsl-<version>.vsix` file and select `Install Extension VSIX`.
+
+### 2.2 Install the CLI:
 
 ```bash
 npm install -g bcs-engineering-dsl
@@ -41,28 +50,30 @@ or link the local version
 npm link
 ```
 
-# 2. Usage
+## 3 Usage
 
-## 2.1 Generate Code
+### 3.1 Generate Code
 
 ```bash
 bcs-engineering-cli beckhoff generate <path-to-bcsctrl-file>
 ```
 
-## 2.2 Generate Code and Deploy
+### 3.2 Generate Code and Deploy
 
 ```bash
 bcs-engineering-cli beckhoff deploy <path-to-bcsctrl-file>
 ```
 
 **NOTE:** The working directory will be set to the root of the provided file. This means that the .bcsctrl file can contain cross-references to other files in the same directory.
 
-## 2.3 Supported Target Platforms
+### 3.3 Supported Target Platforms
 
 Currently the following target platforms are supported:
 
-### 2.3.1 Beckhoff TwinCAT 3
+#### 3.3.1 Beckhoff
 
 In addition to the standard libraries provided by Beckhoff, the following libraries are supported:
 
-- `Tc3_DALI`
+- `Tc3_DALI`: Please note that this library integration is not fully tested.
+
+## 4 Future Work

language/src/cli/cli-util.ts

@@ -13,14 +13,6 @@ import {
   isHardwareModel,
 } from "../language/generated/ast.js";
 
-/**
- * Read a requirement document with the complete workspace (with requirements and
- * tests) located in the folder of the file.
- * @param fileName the main requirement model file
- * @param services the language services
- * @returns a tuple with the document indicated by the fileName and a list of
- *          documents from the workspace.
- */
 export async function extractDocuments(
   fileName: string,
   services: LangiumCoreServices,

language/src/cli/main.ts

@@ -14,8 +14,6 @@ export default function () {
   program.version(pkg.version);
 
   program.addCommand(defineBeckhoffSubcommands());
-  // program.addCommand(defineSiemensSubcommands());
-  // program.addCommand(defineKnxSubcommands());
 
   program.parse();
 }

language/src/cli/platform/beckhoff/application/main-program-generator.ts

@@ -80,7 +80,6 @@ export class MainProgramGenerator {
     );
 
     const declFilePath = path.join(this.destination, `MAIN_decl.st`);
-    // Ensure the destination directory exists
     fs.mkdirSync(this.destination, { recursive: true });
     fs.writeFileSync(declFilePath, declContent);
     const implFilePath = path.join(this.destination, `MAIN_impl.st`);

language/src/cli/platform/beckhoff/application/qualified_reference_name.ts

@@ -25,9 +25,11 @@ export function getReferenceName(ref: Reference<NamedElement>): string {
 
 /**
  * Check if a referenced element belongs to a control unit
- * This helps us determine if we need to qualify the variable name
+ * @param ref Reference to check
+ * @return Tuple where the first element indicates if it's in a control unit,
+ *         and the second element is the control unit name or null
  */
-export function isControlUnitVariable(
+function isControlUnitVariable(
   ref: Reference<NamedElement>
 ): [boolean, string | null] {
   const container = ref?.ref?.$container;

language/src/cli/platform/index.ts

@@ -4,16 +4,11 @@ import type {
 } from "../../language/generated/ast.js";
 import { generate as genBeckhoff } from "./beckhoff/generate.js";
 import { deploy as depBeckhoff } from "./beckhoff/deploy.js";
-//import { generate as genSiemens } from "./siemens/generator.js";
-//import { deploy as depSiemens } from "./siemens/deploy.js";
-//import { generate as genKnx } from "./knx/generator.js";
-//import { deploy as depKnx } from "./knx/deploy.js";
 
 export type Platform = "Beckhoff" | "Siemens" | "KNX";
 
 export interface GenerateResult {
   files: string[];
-  // …any other metadata…
 }
 
 export interface DeployOptions {
@@ -26,7 +21,6 @@ export interface DeployOptions {
   tcExe?: string;
   adsUsername?: string;
   adsPassword?: string;
-  // Siemens/KNX could have their options here
 }
 
 export function generateFor(
@@ -40,10 +34,8 @@ export function generateFor(
       return genBeckhoff(control, hardware, destination);
     case "Siemens":
       throw new Error("Siemens generation not implemented yet");
-    //return genSiemens(control, hardware, destination);
     case "KNX":
       throw new Error("KNX generation not implemented yet");
-    //return genKnx(control, hardware, destination);
     default:
       throw new Error(`Unsupported platform: ${platform}`);
   }
@@ -55,10 +47,8 @@ export function deployTo(platform: Platform, opts: DeployOptions): void {
       return depBeckhoff(opts);
     case "Siemens":
       throw new Error("Siemens deployment not implemented yet");
-    //return depSiemens(opts);
     case "KNX":
       throw new Error("KNX deployment not implemented yet");
-    //return depKnx(opts);
     default:
       throw new Error(`Unsupported platform: ${platform}`);
   }