Metadata-Version: 2.1
Name: cdm-devkit
Version: 0.2.1
Summary: Developer tools for CdM processors
Home-page: https://github.com/cdm-processors/cdm-devkit
Author: CdM Processors
Maintainer: Nikolay Repin
Maintainer-email: n.repin@g.nsu.ru
Requires-Python: >=3.10,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Assemblers
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Disassemblers
Classifier: Topic :: System :: Emulators
Classifier: Topic :: System :: Hardware
Requires-Dist: antlr4-python3-runtime (==4.13.*)
Requires-Dist: bitstruct (>=8.14.1,<9.0.0)
Requires-Dist: colorama (>=0.4.4,<0.5.0)
Requires-Dist: websocket-server (>=0.6.4,<0.7.0)
Description-Content-Type: text/markdown

# Developer tools for Coco-de-Mer processors

## Installation

1. **Download** [latest version](https://github.com/cdm-processors/cdm-devkit/releases/latest)

2. **Install Python package** from `.whl` file
    - Run `pip install cdm-devkit-x.x.x.whl`

    <br>

    > Package will be published to PyPI soon 

3. **Install VS Code extension** from `.vsix` file
    
    > Remove all other extensions that add support for CdM processors

    - Open Command Palette `Ctrl+Shift+P`
    - Type `vsix`
    - Select `Install from VSIX`
    - Select `vscode-cdm-extension-x.x.x.vsix`
    - [Read more](https://code.visualstudio.com/docs/editor/extension-marketplace#_install-from-a-vsix)
    
    <br>

    > Extension will be published to VS Code Marketplace soon 

## Development kit contents

After installation you get several components:

- **CLI Programs**
    
    - `cocas` - assembler for CdM processors
    - `cocodump` - disassembler for CdM processors
    - `synthm` - secondary decoder synthesis utility
    - *(coming soon)*

- **VS Code Extension**

    - Assembler language support for all CdM processors (syntax highlighting and code snippets)
    - Debug support *(coming soon)*

- **cdm-devkit-misc** archive

    - Processor implementations (`./`)
    - Logisim libraries (`jar/`)
        
        - `logisim-banked-memory` - banked memory for `cdm16`
        - `logisim-cdm-emulator` - emulated CdM processors
    - Code and scheme examples (`examples/`)

## Getting started

Check out our [Getting Stated](/docs/getting-started.md) guide.

## Documentation

We are working on documentation, it will be available soon.

However, some docs are available in `docs/` directory.

## Report a bug

You can report a bug with GitHub Issues.

- Open new issue [here](https://github.com/cdm-processors/cdm-devkit/issues)

- Use a template

- Provide a proper name and description of a problem

- Provide information on how to reproduce a bug

## Setting up development environment

- **Python-based projects** use `Poetry` as build system

    - [Install](https://python-poetry.org/docs/#installation) `Poetry`

    - Run `poetry install` to download dependencies

    > `cocas` uses `ANTLR` to parse assembly language
    >
    >    - `antlr4-python3-runtime` is needed to run `cocas` and is installed with other dependencies
    >
    >   - However, if you want to fiddle with grammar files and generate new parser you would need to install `antlr4-tools`, this package is installed with development dependencies ([Read more](https://www.antlr.org))

- **Java-based projects** use `Gradle` as build system

    - Install `JDK`

    - `gradlew` script should download `Gradle` automatically on first run

- **VS Code Extension** uses [official tools](https://code.visualstudio.com/api)

## Building

### Building individual projects

- **Python-based projects:**

    - Run `poetry build`

- **Java-based projects:**
    
    - Navigate to project folder

    - Run `./gradlew jar` (on Unix)
    - Run `.\gradlew.bat jar` (on Windows)

- **VS Code extension:**

    - Navigate to `vscode-cdm-extension/`

    - Run `vsce package`

### Building all projects at once

There is a `Makefile` that will build all projects and prepare files for distribution

- Run `make` to build all projects

<br>

Set `VERSION` variable if you want to specify project version
- Example: `make VERSION=1.2.3`
- `VERSION` should be valid SemVer version

<br>

> You can get `make` on Windows from GnuWin32 project.
> - For Windows 10 and above: 
>   - Run `winget install GnuWin32.Make`
>   - Maybe you would need to add `bin/` directory of make to your `PATH`
> - Using `Chocolatey`:
>   - Run `choco install make` 
> - You can read about other installation methods [here](https://gnuwin32.sourceforge.net/packages/make.htm)

## Contributing

- All contributions should be done via **pull requests**.

- Commit messages should be written according to [these guidelines](https://gist.github.com/robertpainsi/b632364184e70900af4ab688decf6f53)

- Commit messages should start with a **scope identifier** - project name surrounded by square brackets. That will help to determine which project commit belongs to.

**Example:** `[cocas] Add new feature`

> Commits related to whole repository shouldn't use scope identifier

**Possible scope identifiers are:**

- **General:**
    
    - `docs`
    - `ci/cd`
    - `examples`
    - `tests`

- **Processor implementations:**

    - `cdm*`

- **Projects:**

    - `cocas`
    - `cocoemu`
    - `cocodump`
    - `synthm`
    - `logisim-banked-memory`
    - `logisim-cdm-emulator`
    - `logisim-runner`
    - `vscode-cdm-extension`

## Contact us

- If you have a proposal or a suggestion you are free to open a GitHub Issue [here](https://github.com/cdm-processors/cdm-devkit/issues).

- For other questions contact:
    - Email: n.repin@g.nsu.ru
    - Telegram: [@cdm_updates](https://t.me/cdm_updates)

        *(channel with updates, linked chat for support)*

