initial
This commit is contained in:
179
readme.md
Normal file
179
readme.md
Normal file
@@ -0,0 +1,179 @@
|
||||
# @git.zone/tsrust
|
||||
|
||||
A CLI build tool for Rust projects that follows the same conventions as `@git.zone/tsbuild`. It detects your `rust/` source directory, parses `Cargo.toml` (including workspaces), runs `cargo build --release`, and copies the resulting binaries into a clean `dist_rust/` directory at the project root.
|
||||
|
||||
## Issue Reporting and Security
|
||||
|
||||
For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
|
||||
|
||||
## Install
|
||||
|
||||
Install globally via npm:
|
||||
|
||||
```bash
|
||||
npm install -g @git.zone/tsrust
|
||||
```
|
||||
|
||||
Or as a project-level dev dependency:
|
||||
|
||||
```bash
|
||||
pnpm install --save-dev @git.zone/tsrust
|
||||
```
|
||||
|
||||
> ⚡ **Prerequisite:** You need a working Rust toolchain. Install via [rustup.rs](https://rustup.rs/) if you haven't already.
|
||||
|
||||
## The Convention
|
||||
|
||||
`tsrust` mirrors the directory convention established by `tsbuild`:
|
||||
|
||||
| Tool | Source Directory | Output Directory |
|
||||
|------|-----------------|-----------------|
|
||||
| `tsbuild` | `ts/` | `dist_ts/` |
|
||||
| **`tsrust`** | **`rust/`** | **`dist_rust/`** |
|
||||
|
||||
Your Rust code lives in `rust/` (or `ts_rust/` as fallback), and compiled binaries land in `dist_rust/` — ready for packaging, deployment, or further tooling.
|
||||
|
||||
## Usage
|
||||
|
||||
### 🔨 Build (Default Command)
|
||||
|
||||
Simply run `tsrust` from your project root:
|
||||
|
||||
```bash
|
||||
tsrust
|
||||
```
|
||||
|
||||
This will:
|
||||
1. Verify that `cargo` is available
|
||||
2. Locate your `rust/` directory (containing `Cargo.toml`)
|
||||
3. Parse the workspace to discover all `[[bin]]` targets
|
||||
4. Run `cargo build --release` with full streaming output
|
||||
5. Copy each binary to `dist_rust/` with executable permissions (`chmod 755`)
|
||||
6. Report file sizes and total build time
|
||||
|
||||
**Example output:**
|
||||
|
||||
```
|
||||
Using cargo 1.90.0 (840b83a10 2025-07-30)
|
||||
Found Rust project at: rust
|
||||
Detected Cargo workspace
|
||||
Binary targets: rustproxy
|
||||
Running: cargo build --release
|
||||
Compiling rustproxy v0.1.0
|
||||
Finished `release` profile [optimized] target(s) in 29.01s
|
||||
Copied rustproxy (13.4 MB) -> dist_rust/rustproxy
|
||||
Done in 29.2s
|
||||
```
|
||||
|
||||
### 🐛 Debug Build
|
||||
|
||||
Build with the debug profile instead of release:
|
||||
|
||||
```bash
|
||||
tsrust --debug
|
||||
```
|
||||
|
||||
Binaries are taken from `rust/target/debug/` instead of `rust/target/release/`.
|
||||
|
||||
### 🧹 Clean Before Building
|
||||
|
||||
Run `cargo clean` before building to force a full rebuild:
|
||||
|
||||
```bash
|
||||
tsrust --clean
|
||||
```
|
||||
|
||||
### 🗑️ Clean Only
|
||||
|
||||
Remove all build artifacts without rebuilding:
|
||||
|
||||
```bash
|
||||
tsrust clean
|
||||
```
|
||||
|
||||
This runs `cargo clean` in the Rust directory and deletes the `dist_rust/` output directory.
|
||||
|
||||
## Project Structure
|
||||
|
||||
`tsrust` expects your project to follow this layout:
|
||||
|
||||
```
|
||||
my-project/
|
||||
├── rust/ # 🦀 Your Rust source code
|
||||
│ ├── Cargo.toml # Root manifest (workspace or single crate)
|
||||
│ ├── src/
|
||||
│ │ └── main.rs # (for single-crate projects)
|
||||
│ └── crates/ # (for workspace projects)
|
||||
│ ├── my-binary/
|
||||
│ │ ├── Cargo.toml # Contains [[bin]] targets
|
||||
│ │ └── src/
|
||||
│ └── my-lib/
|
||||
│ ├── Cargo.toml
|
||||
│ └── src/
|
||||
├── dist_rust/ # 📦 Output: compiled binaries go here
|
||||
│ └── my-binary
|
||||
├── ts/ # (your TypeScript code, built by tsbuild)
|
||||
├── dist_ts/ # (TypeScript output)
|
||||
└── package.json
|
||||
```
|
||||
|
||||
### Workspace Support
|
||||
|
||||
`tsrust` fully supports Cargo workspaces. It reads the `[workspace]` section from your root `Cargo.toml`, iterates through all `members`, and discovers binary targets from each member crate's `Cargo.toml`.
|
||||
|
||||
Binary target discovery follows Cargo's own rules:
|
||||
- **Explicit `[[bin]]` entries** → uses the `name` field from each entry
|
||||
- **Implicit binary** → if no `[[bin]]` is declared but `src/main.rs` exists, uses the `[package] name`
|
||||
- **Library-only crates** → skipped (no binary output expected)
|
||||
|
||||
### Fallback Directory
|
||||
|
||||
If no `rust/` directory is found, `tsrust` checks for `ts_rust/` as a fallback. This supports projects that use the `ts_` prefix convention for all source directories.
|
||||
|
||||
## Programmatic API
|
||||
|
||||
`tsrust` exports its internals for use in other Node.js/TypeScript tools:
|
||||
|
||||
```typescript
|
||||
import { CargoConfig, CargoRunner, FsHelpers, TsRustCli } from '@git.zone/tsrust';
|
||||
|
||||
// Parse a Cargo workspace
|
||||
const config = new CargoConfig('/path/to/rust');
|
||||
const info = await config.parse();
|
||||
console.log(info.isWorkspace); // true
|
||||
console.log(info.binTargets); // ['rustproxy']
|
||||
|
||||
// Run cargo build
|
||||
const runner = new CargoRunner('/path/to/rust');
|
||||
const result = await runner.build({ debug: false, clean: false });
|
||||
console.log(result.success); // true
|
||||
console.log(result.exitCode); // 0
|
||||
|
||||
// File helpers
|
||||
await FsHelpers.ensureEmptyDir('/path/to/dist_rust');
|
||||
await FsHelpers.copyFile(src, dest);
|
||||
await FsHelpers.makeExecutable(dest);
|
||||
const size = await FsHelpers.getFileSize(dest);
|
||||
console.log(FsHelpers.formatFileSize(size)); // "13.4 MB"
|
||||
```
|
||||
|
||||
## License and Legal Information
|
||||
|
||||
This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
|
||||
|
||||
**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
|
||||
|
||||
### Trademarks
|
||||
|
||||
This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
|
||||
|
||||
Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
|
||||
|
||||
### Company Information
|
||||
|
||||
Task Venture Capital GmbH
|
||||
Registered at District Court Bremen HRB 35230 HB, Germany
|
||||
|
||||
For any legal inquiries or further information, please contact us via email at hello@task.vc.
|
||||
|
||||
By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.
|
||||
Reference in New Issue
Block a user