# Library API Overview
msvc-kit can be used as a Rust library for programmatic access to MSVC toolchain management.
## Installation
Add to your `Cargo.toml`:
```toml
[dependencies]
msvc-kit = "0.1"
tokio = { version = "1", features = ["full"] }
```
## Quick Example
```rust
use msvc_kit::{download_msvc, download_sdk, setup_environment, DownloadOptions};
#[tokio::main]
async fn main() -> msvc_kit::Result<()> {
// Download with default options
let options = DownloadOptions::default();
let msvc_info = download_msvc(&options).await?;
let sdk_info = download_sdk(&options).await?;
// Setup environment
let env = setup_environment(&msvc_info, Some(&sdk_info))?;
// Access paths
println!("cl.exe: {:?}", env.cl_exe_path());
println!("INCLUDE: {}", env.include_path_string());
println!("LIB: {}", env.lib_path_string());
Ok(())
}
```
## Main Types
### Version Discovery Functions
```rust
/// Fetch available versions from Microsoft servers
pub async fn list_available_versions() -> Result<AvailableVersions>;
/// Available version information
pub struct AvailableVersions {
pub msvc_versions: Vec<String>, // e.g., ["14.44", "14.43", "14.42"]
pub sdk_versions: Vec<String>, // e.g., ["10.0.26100.0", "10.0.22621.0"]
pub latest_msvc: Option<String>, // e.g., Some("14.44")
pub latest_sdk: Option<String>, // e.g., Some("10.0.26100.0")
}
```
**Example:**
```rust
use msvc_kit::list_available_versions;
#[tokio::main]
async fn main() -> msvc_kit::Result<()> {
let versions = list_available_versions().await?;
println!("Latest MSVC: {:?}", versions.latest_msvc);
println!("Latest SDK: {:?}", versions.latest_sdk);
println!("\nAvailable MSVC versions:");
for v in &versions.msvc_versions {
println!(" {}", v);
}
Ok(())
}
```
### Download Functions
```rust
/// Download MSVC compiler components
pub async fn download_msvc(options: &DownloadOptions) -> Result<InstallInfo>;
/// Download Windows SDK components
pub async fn download_sdk(options: &DownloadOptions) -> Result<InstallInfo>;
```
### Environment Functions
```rust
/// Setup environment from install info
pub fn setup_environment(
msvc_info: &InstallInfo,
sdk_info: Option<&InstallInfo>,
) -> Result<MsvcEnvironment>;
/// Get environment variables as HashMap
pub fn get_env_vars(env: &MsvcEnvironment) -> HashMap<String, String>;
```
### Script Generation Functions
```rust
/// Generate portable scripts (relative paths, for bundles)
pub fn generate_portable_scripts(ctx: &ScriptContext) -> Result<GeneratedScripts>;
/// Generate absolute path scripts (for installed environments)
pub fn generate_absolute_scripts(ctx: &ScriptContext) -> Result<GeneratedScripts>;
/// Generate a single script for specified shell
pub fn generate_script(ctx: &ScriptContext, shell: ShellType) -> Result<String>;
/// Save scripts to a directory
pub async fn save_scripts(
scripts: &GeneratedScripts,
output_dir: &Path,
base_name: &str,
) -> Result<()>;
```
### Script Context
```rust
/// Create portable script context (uses relative paths like %~dp0)
let ctx = ScriptContext::portable(
"14.44.34823", // MSVC version
"10.0.26100.0", // SDK version
Architecture::X64, // Target arch
Architecture::X64, // Host arch
);
/// Create absolute script context (uses actual paths)
let ctx = ScriptContext::absolute(
PathBuf::from("C:/msvc-kit"),
"14.44.34823",
"10.0.26100.0",
Architecture::X64,
Architecture::X64,
);
```
### Configuration Functions
```rust
/// Load configuration from disk
pub fn load_config() -> Result<MsvcKitConfig>;
/// Save configuration to disk
pub fn save_config(config: &MsvcKitConfig) -> Result<()>;
```
## Re-exported Types
```rust
pub use config::MsvcKitConfig;
pub use downloader::{DownloadOptions, AvailableVersions, list_available_versions};
pub use env::{MsvcEnvironment, ToolPaths};
pub use error::{MsvcKitError, Result};
pub use installer::InstallInfo;
pub use scripts::{GeneratedScripts, ScriptContext, ShellType};
pub use version::{Architecture, MsvcVersion, SdkVersion};
```
## Error Handling
All functions return `msvc_kit::Result<T>`:
```rust
use msvc_kit::{download_msvc, DownloadOptions, MsvcKitError};
async fn example() {
let options = DownloadOptions::default();
match download_msvc(&options).await {
Ok(info) => println!("Installed to {:?}", info.install_path),
Err(MsvcKitError::NetworkError(e)) => eprintln!("Network error: {}", e),
Err(MsvcKitError::VersionNotFound(v)) => eprintln!("Version not found: {}", v),
Err(e) => eprintln!("Error: {}", e),
}
}
```
## Feature Flags
msvc-kit provides optional features to reduce dependency conflicts:
### `self-update` (default)
Enables the CLI self-update functionality. This feature includes the `self_update` crate which depends on `lzma-sys`.
```toml
# Include self-update (default)
[dependencies]
msvc-kit = "0.1"
# Or explicitly enable
[dependencies]
msvc-kit = { version = "0.1", features = ["self-update"] }
```
### Library-only Usage (No Self-update)
If you're using msvc-kit as a library and encounter dependency conflicts (e.g., with `liblzma-sys`), you can disable the default features:
```toml
[dependencies]
msvc-kit = { version = "0.1", default-features = false }
```
This is useful when integrating msvc-kit into projects that use different LZMA implementations, avoiding the `lzma-sys` conflict:
```
error: the crate `lzma` is compiled multiple times, possibly with different configurations
- crate `liblzma_sys` links to native library `lzma`
- crate `lzma_sys` links to native library `lzma`
```
## Thread Safety
- `DownloadOptions`, `InstallInfo`, `MsvcEnvironment` are `Send + Sync`
- Download functions are async and can be called from any runtime
- Configuration functions use file locking for concurrent access
## Next Steps
- [DownloadOptions](./download-options.md) - Configure downloads
- [InstallInfo](./install-info.md) - Access installation details
- [MsvcEnvironment](./msvc-environment.md) - Environment configuration
- [ToolPaths](./tool-paths.md) - Access tool executables