jesus/nushell-plugins
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
nushell-plugins/docs/building.md
Jesús Pérez d9ef2f0d5b
Some checks failed
Build and Test / Validate Setup (push) Has been cancelled
Details
Build and Test / Build (darwin-amd64) (push) Has been cancelled
Details
Build and Test / Build (darwin-arm64) (push) Has been cancelled
Details
Build and Test / Build (linux-amd64) (push) Has been cancelled
Details
Build and Test / Build (windows-amd64) (push) Has been cancelled
Details
Build and Test / Build (linux-arm64) (push) Has been cancelled
Details
Build and Test / Security Audit (push) Has been cancelled
Details
Build and Test / Package Results (push) Has been cancelled
Details
Build and Test / Quality Gate (push) Has been cancelled
Details
Nightly Build / Check for Changes (push) Has been cancelled
Details
Nightly Build / Validate Setup (push) Has been cancelled
Details
Nightly Build / Nightly Build (darwin-amd64) (push) Has been cancelled
Details
Nightly Build / Nightly Build (darwin-arm64) (push) Has been cancelled
Details
Nightly Build / Nightly Build (linux-amd64) (push) Has been cancelled
Details
Nightly Build / Nightly Build (windows-amd64) (push) Has been cancelled
Details
Nightly Build / Nightly Build (linux-arm64) (push) Has been cancelled
Details
Nightly Build / Create Nightly Pre-release (push) Has been cancelled
Details
Nightly Build / Notify Build Status (push) Has been cancelled
Details
Nightly Build / Nightly Maintenance (push) Has been cancelled
Details
chore: update all plugins to Nushell 0.111.0 
- Bump all 18 plugins from 0.110.0 to 0.111.0
  - Update rust-toolchain.toml channel to 1.93.1 (nu 0.111.0 requires ≥1.91.1)

  Fixes:
  - interprocess pin =2.2.x → ^2.3.1 in nu_plugin_mcp, nu_plugin_nats, nu_plugin_typedialog
    (required by nu-plugin-core 0.111.0)
  - nu_plugin_typedialog: BackendType::Web initializer — add open_browser: false field
  - nu_plugin_auth: implement missing user_info_to_value helper referenced in tests

  Scripts:
  - update_all_plugins.nu: fix [package].version update on minor bumps; add [dev-dependencies]
    pass; add nu-plugin-test-support to managed crates
  - download_nushell.nu: rustup override unset before rm -rf on nushell dir replace;
    fix unclosed ) in string interpolation
2026-03-11 03:22:42 +00:00

20 KiB
Raw Permalink Blame History

Building and Cross-Compilation Guide\n\nThis comprehensive guide covers everything you need to know about building nushell plugins, including cross-compilation for multiple platforms.\n\n## Table of Contents\n\n- Quick Start\n- Prerequisites\n- Build Methods\n- Cross-Compilation\n- Docker Builds\n- Platform Support\n- Configuration\n- Workflows\n- Distribution\n- Troubleshooting\n- FAQ\n- Advanced Topics\n\n## Quick Start\n\n### Native Build (Host Platform Only)\n\nbash\n# Clone repository\ngit clone https://github.com/YOUR_ORG/nushell-plugins.git\ncd nushell-plugins\n\n# Build all plugins for your platform\njust build\n\n# Or using the script directly\n./scripts/run.sh build_all.nu\n\n\n### Cross-Platform Build\n\nbash\n# Build for all supported platforms\njust build-cross-all\n\n# Build for specific platform\njust build-cross linux-amd64\n\n# Build and create distribution packages\njust release-cross\n\n\n## Prerequisites\n\n### Required Tools\n\n1. Rust Toolchain (1.70.0+)\n\n bash\n curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\n \n\n2. Nushell (0.107.1)\n\n bash\n # Install via cargo\n cargo install nu\n\n # Or download from https://github.com/nushell/nushell/releases\n \n\n3. Just (optional but recommended)\n\n bash\n cargo install just\n \n\n4. Git with submodules\n\n bash\n git clone --recursive https://github.com/YOUR_ORG/nushell-plugins.git\n \n\n### Optional Tools\n\n- Docker - For Docker-based cross-compilation\n- Cross-compilation toolchains - For native cross-compilation\n\n## Build Methods\n\n### 1. Native Compilation\n\nBuild plugins for your current platform using the standard Rust toolchain.\n\nbash\n# Basic build\njust build\n\n# Verbose output\njust build-verbose\n\n# Parallel build (experimental)\njust build-parallel\n\n# Build specific plugins\n./scripts/run.sh build_all.nu --plugins nu_plugin_clipboard,nu_plugin_image\n\n\nPros:\n\n- Fast compilation\n- Native debugging support\n- Simple setup\n\nCons:\n\n- Only builds for current platform\n- Limited cross-compilation support\n\n### 2. Cross-Compilation\n\nBuild plugins for different platforms using Rust's cross-compilation features.\n\nbash\n# List available targets\njust build-targets\n\n# Build for specific target\njust build-cross linux-amd64\njust build-cross darwin-arm64\njust build-cross windows-amd64\n\n# Build for all targets\njust build-cross-all\n\n# Parallel cross-compilation\njust build-cross-parallel\n\n\nPros:\n\n- Multiple platforms from single machine\n- Fast execution\n- No Docker dependency\n\nCons:\n\n- May require target-specific toolchains\n- Some targets may not work on all hosts\n\n### 3. Docker-Based Cross-Compilation\n\nUse Docker containers with pre-configured cross-compilation environments.\n\nbash\n# Build Docker image\njust build-docker-image\n\n# Build specific target with Docker\njust build-docker linux-arm64\n\n# Force Docker for all builds\n./scripts/run.sh build_cross.nu --all-targets --docker\n\n\nPros:\n\n- Consistent build environment\n- All toolchains pre-installed\n- Works on any Docker-capable host\n\nCons:\n\n- Slower than native compilation\n- Requires Docker\n- Larger resource usage\n\n## Cross-Compilation\n\n### Supported Platforms\n\n| Platform | Target Triple | Native | Docker | Notes |\n|----------|---------------|--------|---------|-------|\n| Linux AMD64 | x86_64-unknown-linux-gnu | ✅ | ✅ | Most common Linux |\n| Linux ARM64 | aarch64-unknown-linux-gnu | ⚠️ | ✅ | Requires cross toolchain |\n| macOS Intel | x86_64-apple-darwin | 🍎 | ❌ | macOS host only |\n| macOS Apple Silicon | aarch64-apple-darwin | 🍎 | ❌ | macOS host only |\n| Windows AMD64 | x86_64-pc-windows-msvc | 🪟 | ✅ | Windows host or Docker |\n\nLegend:\n\n- ✅ Fully supported\n- ⚠️ Requires additional setup\n- 🍎 macOS host required\n- 🪟 Windows host required\n- ❌ Not supported\n\n### Setting Up Cross-Compilation\n\n#### Linux → Linux ARM64\n\nbash\n# Install cross-compilation toolchain (Ubuntu/Debian)\nsudo apt-get install gcc-aarch64-linux-gnu\n\n# Add Rust target\nrustup target add aarch64-unknown-linux-gnu\n\n# Configure environment\nexport CC_aarch64_unknown_linux_gnu=aarch64-linux-gnu-gcc\nexport CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-linux-gnu-gcc\n\n# Build\njust build-cross linux-arm64\n\n\n#### Any → Windows (Docker)\n\nbash\n# Build Docker image with Windows toolchain\njust build-docker-image\n\n# Cross-compile to Windows\njust build-docker windows-amd64\n\n\n### Configuration Files\n\n#### Build Targets (etc/build_targets.toml)\n\ntoml\n[targets.linux-amd64]\nrust_target = "x86_64-unknown-linux-gnu"\nplatform_name = "linux-amd64"\narchive_format = "tar.gz"\ndocker_required = false\nnative_build = true\ndescription = "Linux x86_64 (64-bit Intel/AMD)"\n\n[targets.linux-arm64]\nrust_target = "aarch64-unknown-linux-gnu"\nplatform_name = "linux-arm64"\narchive_format = "tar.gz"\ndocker_required = true\nnative_build = false\ndescription = "Linux ARM64 (64-bit ARM)"\nlinker = "aarch64-linux-gnu-gcc"\n\n\n#### Environment Variables\n\nbash\n# Cross-compilation linkers\nexport CC_aarch64_unknown_linux_gnu=aarch64-linux-gnu-gcc\nexport CXX_aarch64_unknown_linux_gnu=aarch64-linux-gnu-g++\nexport AR_aarch64_unknown_linux_gnu=aarch64-linux-gnu-ar\n\n# Cargo configuration\nexport CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-linux-gnu-gcc\n\n\n## Docker Builds\n\n### Docker Image\n\nThe cross-compilation Docker image includes:\n\n- Rust toolchain (1.75.0)\n- Cross-compilation targets for all supported platforms\n- System toolchains (GCC, MinGW, etc.)\n- Build tools (cargo, rustfmt, clippy)\n\n### Docker Commands\n\nbash\n# Build Docker image\njust build-docker-image\n\n# Rebuild from scratch\njust build-docker-image-fresh\n\n# Show Docker environment info\njust docker-info\n\n# Build specific plugin with Docker\njust build-docker-plugin nu_plugin_clipboard linux-arm64\n\n# Clean up Docker artifacts\njust docker-cleanup\n\n\n### Docker Workflow\n\nbash\n# Complete Docker-based workflow\njust docker-flow\n\n# This runs:\n# 1. just validate-nushell\n# 2. just build-docker-image\n# 3. just build-cross-all --docker\n# 4. just collect-all\n# 5. just pack-all\n\n\n### Manual Docker Usage\n\nbash\n# Run interactive Docker container\ndocker run -it --rm \n -v $(pwd):/workspace \n -w /workspace \n nushell-plugins-cross:latest \n bash\n\n# Build specific target in container\ndocker run --rm \n -v $(pwd):/workspace \n -w /workspace/nu_plugin_clipboard \n nushell-plugins-cross:latest \n cargo build --release --target aarch64-unknown-linux-gnu\n\n\n## Platform Support\n\n### Linux\n\nSupported Architectures:\n\n- x86_64 (AMD64) - Native and Docker\n- ARM64 (AArch64) - Docker recommended\n- ARM32 (ARMv7) - Docker only, disabled by default\n\nDependencies:\n\nbash\n# Ubuntu/Debian\nsudo apt-get install build-essential libssl-dev pkg-config\n\n# Cross-compilation toolchains\nsudo apt-get install gcc-aarch64-linux-gnu gcc-arm-linux-gnueabihf\n\n\n### macOS\n\nSupported Architectures:\n\n- Intel (x86_64) - Native only\n- Apple Silicon (ARM64) - Native only\n\nDependencies:\n\nbash\n# Install Xcode command line tools\nxcode-select --install\n\n# Add Rust targets\nrustup target add x86_64-apple-darwin aarch64-apple-darwin\n\n\nCross-compilation:\n\nbash\n# On Apple Silicon, build for Intel\njust build-cross darwin-amd64\n\n# On Intel, build for Apple Silicon (may not work)\njust build-cross darwin-arm64\n\n\n### Windows\n\nSupported Architectures:\n\n- x86_64 (AMD64) - Native and Docker\n\nNative Dependencies:\n\n- Visual Studio Build Tools or Visual Studio Community\n- Windows SDK\n\nDocker Alternative:\n\nbash\n# Use Docker for Windows builds on any platform\njust build-docker windows-amd64\n\n\n## Configuration\n\n### Global Configuration\n\nThe main configuration file is etc/build_targets.toml:\n\ntoml\n[metadata]\nversion = "1.0.0"\ndescription = "Cross-compilation targets for nushell plugins"\n\n[defaults]\ndocker_image = "nushell-plugins-cross:latest"\nstrip_binaries = true\noptimize_size = true\n\n[targets.custom-target]\nrust_target = "x86_64-unknown-linux-musl"\nplatform_name = "linux-amd64-musl"\narchive_format = "tar.gz"\ndocker_required = false\ndescription = "Linux x86_64 with musl libc"\nenabled = true\n\n\n### Environment Configuration\n\nCreate an env file for local overrides:\n\nbash\n# env file\nTARGET_PATH=distribution\nINSTALL_BIN_PATH=/usr/local/bin\nBIN_ARCHIVES_DIR_PATH=bin_archives\nAPP_NAME=nushell-plugins\n\n\n### Plugin-Specific Configuration\n\nSome plugins may require special build configurations:\n\ntoml\n# In plugin's Cargo.toml\n[package.metadata.cross]\nimage = "ghcr.io/cross-rs/cross:aarch64-unknown-linux-gnu"\n\n[target.aarch64-unknown-linux-gnu]\nlinker = "aarch64-linux-gnu-gcc"\n\n\n## Workflows\n\n### Development Workflows\n\n#### Standard Development\n\nbash\njust dev-flow\n# 1. Validate nushell version\n# 2. Check upstream changes\n# 3. Build for host platform\n# 4. Run tests\n# 5. Show status\n\n\n#### Cross-Platform Development\n\nbash\njust dev-flow-cross\n# 1. Validate nushell version\n# 2. Check upstream changes\n# 3. Build for all platforms\n# 4. Show status\n\n\n#### Quality Assurance\n\nbash\njust quality-flow\n# 1. Validate nushell version\n# 2. Format code\n# 3. Run clippy linting\n# 4. Run tests\n\n\n### Release Workflows\n\n#### Standard Release\n\nbash\njust release-flow\n# 1. Validate nushell version\n# 2. Build for host platform\n# 3. Collect binaries\n# 4. Create packages\n\n\n#### Cross-Platform Release\n\nbash\njust release-flow-cross\n# 1. Validate nushell version\n# 2. Build for all platforms\n# 3. Collect all binaries\n# 4. Create packages with checksums\n\n\n#### CI Simulation\n\nbash\njust ci-flow\n# Simulates exactly what GitHub Actions will run\n\n\n### Custom Workflows\n\nYou can create custom workflows by combining individual commands:\n\nbash\n# Custom workflow for testing\njust validate-nushell\njust build-cross linux-amd64\njust build-cross darwin-arm64\njust test\njust collect-platform linux-amd64\njust pack-platform linux-amd64\n\n\n## Distribution\n\n### Collection\n\nCollect built binaries for distribution:\n\nbash\n# Collect all platforms\njust collect-all\n\n# Collect specific platform\njust collect-platform linux-amd64\n\n# List what can be collected\njust collect-platforms\n\n\n### Packaging\n\nCreate distribution archives:\n\nbash\n# Package all platforms\njust pack-all\n\n# Package with checksums\njust pack-checksums\n\n# Package specific platform\njust pack-platform darwin-arm64\n\n# List packaging options\njust pack-platforms\n\n\n### Directory Structure\n\nAfter building and packaging:\n\nplaintext\ndistribution/\n├── linux-amd64/\n│ ├── nu_plugin_clipboard\n│ ├── nu_plugin_image\n│ ├── install_nu_plugins.nu\n│ ├── LICENSE\n│ └── README\n├── darwin-arm64/\n│ └── [same structure]\n└── windows-amd64/\n ├── nu_plugin_clipboard.exe\n └── [same structure]\n\nbin_archives/\n├── linux-amd64-nushell-plugins.tar.gz\n├── darwin-arm64-nushell-plugins.tar.gz\n├── windows-amd64-nushell-plugins.zip\n└── checksums.txt\n\n\n### Checksums\n\nAll distribution packages include SHA256 checksums:\n\nbash\n# Generate checksums\njust pack-checksums\n\n# Verify downloaded archive\nsha256sum -c checksums.txt\n\n# Manual verification\nsha256sum linux-amd64-nushell-plugins.tar.gz\n\n\n## Troubleshooting\n\n### Common Issues\n\n#### Version Mismatch\n\nbash\n# Error: Nushell version mismatch detected\n# Fix: Update versions automatically\njust fix-nushell\n\n# Or manually check and fix\n./scripts/run.sh check_version.nu --fix\n\n\n#### Missing Cross-Compilation Target\n\nbash\n# Error: target 'aarch64-unknown-linux-gnu' not found\n# Fix: Install the target\nrustup target add aarch64-unknown-linux-gnu\n\n\n#### Cross-Compilation Linker Error\n\nbash\n# Error: linker 'aarch64-linux-gnu-gcc' not found\n# Fix: Install cross-compilation toolchain\nsudo apt-get install gcc-aarch64-linux-gnu\n\n# Set environment variable\nexport CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-linux-gnu-gcc\n\n\n#### Docker Build Failures\n\nbash\n# Error: Docker daemon not running\n# Fix: Start Docker service\nsudo systemctl start docker\n\n# Error: Docker image not found\n# Fix: Build the image\njust build-docker-image\n\n# Error: Permission denied in Docker\n# Fix: Add user to docker group\nsudo usermod -aG docker $USER\n\n\n#### Build Failures\n\nPlugin-specific failures:\n\nbash\n# Debug specific plugin\ncd nu_plugin_clipboard\ncargo build --release --verbose\n\n# Check plugin dependencies\ncargo tree\n\n\nCross-compilation failures:\n\nbash\n# Use Docker instead of native cross-compilation\njust build-docker linux-arm64\n\n# Check target support\nrustup target list | grep installed\n\n\n### Debug Mode\n\nEnable verbose output for troubleshooting:\n\nbash\n# Verbose build output\njust build-verbose\n\n# Verbose cross-compilation\n./scripts/run.sh build_cross.nu --all-targets --verbose\n\n# Debug Docker builds\n./scripts/run.sh build_docker_cross.nu --verbose\n\n\n### Log Files\n\nBuild logs are preserved for debugging:\n\nbash\n# View recent build logs\nls -la target/*/build/*/out/\n\n# Search for specific errors\ngrep -r "error" target/*/build/*/stderr\n\n\n## FAQ\n\n### General Questions\n\nQ: What platforms are supported?\nA: Linux (AMD64, ARM64), macOS (Intel, Apple Silicon), and Windows (AMD64). See the Platform Support section for details.\n\nQ: Do I need Docker for cross-compilation?\nA: Not always. Native cross-compilation works for many targets, but Docker provides a more consistent environment and supports more target combinations.\n\nQ: How long does cross-compilation take?\nA: Building all platforms takes 10-30 minutes depending on your hardware. Parallel builds (just build-cross-parallel) can significantly reduce this time.\n\nQ: Can I add new platforms?\nA: Yes! Edit etc/build_targets.toml to add new targets. See Configuration for details.\n\n### Build Questions\n\nQ: Why do some builds fail on my platform?\nA: Cross-compilation has limitations. macOS targets can only be built on macOS, and some Linux ARM64 builds require specific toolchains. Use Docker builds as a fallback.\n\nQ: How can I speed up builds?\nA: Use parallel builds (--parallel), enable incremental compilation, and use Docker layer caching. Consider building only the platforms you need.\n\nQ: Can I build just one plugin?\nA: Yes! Use ./scripts/run.sh build_all.nu --plugins nu_plugin_clipboard or build manually in the plugin directory.\n\nQ: Why are Windows binaries so large?\nA: Windows binaries include the MSVC runtime. You can reduce size by using the GNU toolchain or enabling link-time optimization.\n\n### Docker Questions\n\nQ: How much disk space does the Docker image use?\nA: The cross-compilation image is approximately 2-3 GB, including all toolchains and dependencies.\n\nQ: Can I use my own Docker image?\nA: Yes! Modify the docker.image_tag setting in etc/build_targets.toml to use a custom image.\n\nQ: How do I update the Docker image?\nA: Run just build-docker-image-fresh to rebuild from scratch with the latest dependencies.\n\n### Distribution Questions\n\nQ: How do I install the plugins?\nA: Use the universal installer: curl -L https://github.com/YOUR_ORG/nushell-plugins/releases/latest/download/install.sh | sh\n\nQ: Can I distribute individual plugins?\nA: Yes! Each plugin binary is self-contained. Just copy the nu_plugin_* files to the target system.\n\nQ: What's the difference between tar.gz and zip archives?\nA: Unix-like systems (Linux, macOS) use tar.gz for better compression and permission preservation. Windows uses zip for compatibility.\n\n### Troubleshooting Questions\n\nQ: Build fails with "permission denied" errors\nA: Check that you have write permissions to the target directory and that antivirus software isn't blocking the builds.\n\nQ: Cross-compilation fails with "unsupported target"\nA: Install the target with rustup target add TARGET_NAME or use Docker builds instead.\n\nQ: Docker builds are very slow\nA: Make sure Docker has sufficient resources allocated. Consider using Docker BuildKit for faster builds.\n\n## Advanced Topics\n\n### Custom Build Targets\n\nAdd support for new platforms by editing etc/build_targets.toml:\n\ntoml\n[targets.linux-musl]\nrust_target = "x86_64-unknown-linux-musl"\nplatform_name = "linux-amd64-musl"\narchive_format = "tar.gz"\ndocker_required = false\ndescription = "Linux x86_64 with musl libc"\nstrip_binaries = true\n\n[environment.linux-musl]\nCC = "musl-gcc"\n\n\n### Build Optimization\n\n#### Link-Time Optimization (LTO)\n\ntoml\n# In Cargo.toml\n[profile.release]\nlto = true\ncodegen-units = 1\npanic = "abort"\nstrip = "symbols"\n\n\n#### Size Optimization\n\ntoml\n[profile.release]\nopt-level = "z" # Optimize for size\nlto = true\nstrip = "symbols"\n\n\n#### Build Scripts\n\nCreate custom build scripts for complex scenarios:\n\nbash\n#!/bin/bash\n# scripts/custom_build.sh\n\n# Custom build with specific optimizations\nexport RUSTFLAGS="-C target-cpu=native"\ncargo build --release --target x86_64-unknown-linux-gnu\n\n# Strip debug symbols\nstrip target/x86_64-unknown-linux-gnu/release/nu_plugin_*\n\n\n### Continuous Integration\n\nThe repository includes GitHub Actions workflows for:\n\n- Build & Test (.github/workflows/build.yml)\n- Release (.github/workflows/release.yml)\n- Nightly Builds (.github/workflows/nightly.yml)\n\nTo set up in your own repository:\n\n1. Copy the .github/workflows/ directory\n2. Update the repository references\n3. Configure GitHub secrets if needed\n4. Customize the build matrix for your needs\n\n### Plugin Development\n\nWhen developing new plugins:\n\n1. Use the template:\n\n bash\n just make-plugin nu_plugin_yourname\n \n\n2. Follow the plugin structure:\n\nplaintext\n nu_plugin_yourname/\n ├── Cargo.toml\n ├── src/\n │ ├── main.rs\n │ └── lib.rs\n └── README.md\n \n\n3. Test cross-compilation early:\n\n bash\n just build-cross-all\n \n\n4. Add to the registry:\n Update etc/plugin_registry.toml if the plugin has an upstream repository.\n\n### Performance Tuning\n\n#### Parallel Compilation\n\n\n# Set number of parallel jobs\nexport CARGO_BUILD_JOBS=8\n\n# Use parallel cross-compilation\njust build-cross-parallel\nplaintext\n\n#### Caching\n\n\n# Use sccache for distributed compilation caching\ncargo install sccache\nexport RUSTC_WRAPPER=sccache\nplaintext\n\n#### Memory Usage\n\n\n# Limit memory usage for large builds\nexport CARGO_BUILD_RUSTFLAGS="-C link-arg=-Wl,--no-keep-memory"\nplaintext\n\n---\n\n## Getting Help\n\n- Issues: GitHub Issues\n- Discussions: GitHub Discussions\n- Documentation: Repository Wiki\n- Nushell Community: Discord | Reddit\n\n## Contributing\n\nSee CONTRIBUTING.md for guidelines on contributing to the build system and adding new platforms or features.\n\n---\n\nThis documentation is maintained by the nushell-plugins team. Last updated: 2024-09-20