---
<a id="en"></a>
# self_cmd: Self-Executing Command Builder
- [Overview](#overview)
- [Features](#features)
- [Usage](#usage)
- [Design Philosophy](#design-philosophy)
- [Technical Stack](#technical-stack)
- [Project Structure](#project-structure)
- [API Reference](#api-reference)
- [Historical Context](#historical-context)
## Overview
`self_cmd` is a Rust library that creates Command instances for re-executing the current program with identical arguments and stdio inheritance. This enables programs to spawn themselves as child processes while maintaining the original execution context.
## Features
- **Self-Replication**: Generate Command objects that execute the current program
- **Argument Preservation**: Automatically captures and forwards command-line arguments
- **Stdio Inheritance**: Maintains stdin, stdout, and stderr connections
- **Zero Dependencies**: Lightweight implementation using only standard library
- **Error Handling**: Proper Result-based error propagation
## Usage
Add to your `Cargo.toml`:
```toml
[dependencies]
self_cmd = "0.1.0"
```
Basic usage:
```rust
use self_cmd;
use std::process::Command;
fn main() -> std::io::Result<()> {
// Create a command that will re-execute this program
let mut cmd = self_cmd::get()?;
// Execute the command
let status = cmd.status()?;
println!("Child process exited with: {status}");
Ok(())
}
```
Advanced usage with custom handling:
```rust
use self_cmd;
fn restart_self() -> std::io::Result<()> {
let mut cmd = self_cmd::get()?;
// The command inherits stdio by default
// You can modify it if needed
cmd.spawn()?;
Ok(())
}
```
## Design Philosophy
The library follows a minimalist approach with a single public function that encapsulates the complexity of self-execution:
```mermaid
graph TD
A[Program Start] --> B["self_cmd::get()"]
B --> C["env::current_exe()"]
C --> D["env::args().skip(1)"]
D --> E["Command::new(program)"]
E --> F["cmd.args(args)"]
F --> G[Configure Stdio Inheritance]
G --> H[Return Command]
H --> I[Execute Command]
```
The design ensures:
- **Simplicity**: Single function interface
- **Reliability**: Proper error handling without panics
- **Flexibility**: Returns Command for further customization
- **Performance**: Minimal overhead with lazy evaluation
## Technical Stack
- **Language**: Rust 2024 Edition
- **Dependencies**: Standard library only
- **Error Handling**: `std::io::Result` for I/O operations
- **Process Management**: `std::process::Command`
- **Environment Access**: `std::env` for executable path and arguments
## Project Structure
```
self_cmd/
├── src/
│ └── lib.rs # Core implementation
├── tests/
│ └── main.rs # Integration tests
├── readme/
│ ├── en.md # English documentation
│ └── zh.md # Chinese documentation
├── Cargo.toml # Project configuration
└── test.sh # Test runner script
```
## API Reference
### `get() -> std::io::Result<Command>`
Creates a Command instance configured to re-execute the current program.
**Returns:**
- `Ok(Command)`: Configured command ready for execution
- `Err(std::io::Error)`: If unable to determine current executable path
**Behavior:**
- Captures current executable path via `env::current_exe()`
- Preserves all command-line arguments except program name
- Configures stdio inheritance (stdin, stdout, stderr)
- Returns Command for further customization before execution
**Example:**
```rust
match self_cmd::get() {
Ok(mut cmd) => {
// Command is ready to use
cmd.status()?;
}
Err(e) => {
eprintln!("Failed to create self command: {e}");
}
}
```
## Historical Context
The concept of self-executing programs has deep roots in computer science, dating back to early Unix systems where programs needed to restart themselves for configuration reloads or updates. The `exec` family of system calls in Unix provided the foundation for process replacement, while modern languages like Rust have abstracted this into safer, more ergonomic APIs.
Self-replication patterns became particularly important in:
- **Daemon Management**: Services that need to restart after configuration changes
- **Hot Reloading**: Development tools that rebuild and restart automatically
- **Process Supervision**: Programs that monitor and restart child processes
- **Bootstrapping**: Installation scripts that re-execute with elevated privileges
The Rust ecosystem's emphasis on memory safety and explicit error handling makes it particularly well-suited for implementing reliable self-execution patterns, avoiding the pitfalls of traditional C-based approaches where process management often led to resource leaks or zombie processes.
---
## About
This project is an open-source component of [js0.site ⋅ Refactoring the Internet Plan](https://js0.site).
We are redefining the development paradigm of the Internet in a componentized way. Welcome to follow us:
* [Google Group](https://groups.google.com/g/js0-site)
* [js0site.bsky.social](https://bsky.app/profile/js0site.bsky.social)
---
<a id="zh"></a>
# self_cmd: 自执行命令构建器
- [概述](#概述)
- [功能特性](#功能特性)
- [使用方法](#使用方法)
- [设计理念](#设计理念)
- [技术栈](#技术栈)
- [项目结构](#项目结构)
- [API 参考](#api-参考)
- [历史背景](#历史背景)
## 概述
`self_cmd` 是 Rust 库，用于创建重新执行当前程序的 Command 实例，保持相同参数和标准输入输出继承。使程序能够生成自身的子进程，同时维持原始执行上下文。
## 功能特性
- **自我复制**: 生成执行当前程序的 Command 对象
- **参数保持**: 自动捕获并转发命令行参数
- **标准输入输出继承**: 维持 stdin、stdout、stderr 连接
- **零依赖**: 仅使用标准库的轻量级实现
- **错误处理**: 基于 Result 的错误传播机制
## 使用方法
添加到 `Cargo.toml`:
```toml
[dependencies]
self_cmd = "0.1.0"
```
基本用法:
```rust
use self_cmd;
use std::process::Command;
fn main() -> std::io::Result<()> {
// 创建重新执行此程序的命令
let mut cmd = self_cmd::get()?;
// 执行命令
let status = cmd.status()?;
println!("子进程退出状态: {status}");
Ok(())
}
```
高级用法与自定义处理:
```rust
use self_cmd;
fn restart_self() -> std::io::Result<()> {
let mut cmd = self_cmd::get()?;
// 命令默认继承标准输入输出
// 可根据需要进行修改
cmd.spawn()?;
Ok(())
}
```
## 设计理念
库采用极简主义方法，通过单个公共函数封装自执行的复杂性:
```mermaid
graph TD
A[程序启动] --> B["self_cmd::get()"]
B --> C["env::current_exe()"]
C --> D["env::args().skip(1)"]
D --> E["Command::new(program)"]
E --> F["cmd.args(args)"]
F --> G[配置标准输入输出继承]
G --> H[返回 Command]
H --> I[执行命令]
```
设计确保:
- **简洁性**: 单函数接口
- **可靠性**: 无恐慌的错误处理
- **灵活性**: 返回 Command 供进一步定制
- **性能**: 惰性求值的最小开销
## 技术栈
- **语言**: Rust 2024 版本
- **依赖**: 仅标准库
- **错误处理**: `std::io::Result` 用于 I/O 操作
- **进程管理**: `std::process::Command`
- **环境访问**: `std::env` 获取可执行文件路径和参数
## 项目结构
```
self_cmd/
├── src/
│ └── lib.rs # 核心实现
├── tests/
│ └── main.rs # 集成测试
├── readme/
│ ├── en.md # 英文文档
│ └── zh.md # 中文文档
├── Cargo.toml # 项目配置
└── test.sh # 测试运行脚本
```
## API 参考
### `get() -> std::io::Result<Command>`
创建配置为重新执行当前程序的 Command 实例。
**返回值:**
- `Ok(Command)`: 配置好的命令，可直接执行
- `Err(std::io::Error)`: 无法确定当前可执行文件路径时
**行为:**
- 通过 `env::current_exe()` 捕获当前可执行文件路径
- 保留除程序名外的所有命令行参数
- 配置标准输入输出继承 (stdin, stdout, stderr)
- 返回 Command 供执行前进一步定制
**示例:**
```rust
match self_cmd::get() {
Ok(mut cmd) => {
// 命令已准备就绪
cmd.status()?;
}
Err(e) => {
eprintln!("创建自执行命令失败: {e}");
}
}
```
## 历史背景
自执行程序的概念在计算机科学中根深蒂固，可追溯到早期 Unix 系统，当时程序需要重启自身以重新加载配置或更新。Unix 中的 `exec` 系统调用族为进程替换提供了基础，而 Rust 等现代语言将其抽象为更安全、更符合人体工程学的 API。
自复制模式在以下场景中变得尤为重要:
- **守护进程管理**: 配置更改后需要重启的服务
- **热重载**: 自动重建和重启的开发工具
- **进程监督**: 监控和重启子进程的程序
- **引导程序**: 以提升权限重新执行的安装脚本
Rust 生态系统对内存安全和显式错误处理的重视，使其特别适合实现可靠的自执行模式，避免了传统基于 C 的方法中进程管理经常导致资源泄漏或僵尸进程的陷阱。
---
## 关于
本项目为 [js0.site ⋅ 重构互联网计划](https://js0.site) 的开源组件。
我们正在以组件化的方式重新定义互联网的开发范式，欢迎关注：
* [谷歌邮件列表](https://groups.google.com/g/js0-site)
* [js0site.bsky.social](https://bsky.app/profile/js0site.bsky.social)