dexoron/dcr
1
1
Fork 0
mirror of https://github.com/dexoron/dcr.git synced 2026-10-22 09:49:37 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add and clean up AI-generated rustdoc comments (grok-4.5)

Browse Source
This commit is contained in:
Dexoron
2026-08-05 19:21:00 +08:00
parent bc308d6996
commit a20c61cc88
65 changed files with 1070 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
src/core/deps/common.rs
View File

@@ -1,3 +1,4 @@
/// Represents resolved dependencies for a build target, including include directories, library directories, and libraries.
#[derive(Debug, Clone, Default)]
pub struct ResolvedDeps {
pub include_dirs: Vec<String>,

5
src/core/deps/lock.rs
View File

@@ -18,6 +18,7 @@
use std::fs;
use std::path::Path;
/// Represents a locked dependency entry containing its name, version, source, and checksum.
#[derive(Debug, Clone)]
pub struct DepLock {
pub name: String,
@@ -26,6 +27,7 @@ pub struct DepLock {
pub source: String,
}
/// Writes the dcr.lock file in a Cargo-like format. The project entry comes first, followed by dependency entries.
pub fn write_lock(
project_root: &Path,
project_name: &str,
@@ -47,6 +49,7 @@ pub fn write_lock(
}
out.push('\n');
// Write metadata for each package in the dependencies list
for pkg in packages {
out.push_str("[[package]]\n");
out.push_str(&format!("name = \"{}\"\n", escape_value(&pkg.name)));
@@ -60,6 +63,7 @@ pub fn write_lock(
Ok(())
}
/// Converts a list of strings into a comma-separated TOML array by quoting each item.
fn quote_list(items: &[String]) -> String {
items
.iter()
@@ -68,6 +72,7 @@ fn quote_list(items: &[String]) -> String {
.join(", ")
}
/// Escapes backslashes and double quotes in a string to make it safe for TOML.
fn escape_value(input: &str) -> String {
input.replace('\\', "\\\\").replace('"', "\\\"")
}

23
src/core/deps/mod.rs
View File

@@ -15,6 +15,7 @@
// You should have received a copy of the GNU General Public License
// along with this program. If not, see <https://www.gnu.org/licenses/>.
/// Core dependency resolver for DCR projects.
pub mod common;
pub mod lock;
pub mod register;
@@ -24,6 +25,7 @@ use crate::core::deps::common::ResolvedDeps;
use crate::core::deps::lock::{DepLock, write_lock};
use std::path::Path;
/// Returns the version string from a dependency's dcr.toml file, or an empty string if missing.
fn dep_version(path: &Path) -> String {
Config::open(&path.join("dcr.toml").to_string_lossy())
.ok()
@@ -35,6 +37,18 @@ fn dep_version(path: &Path) -> String {
.unwrap_or_default()
}
/// Resolves dependencies from config into include/lib dirs and lib names, and writes the lock file.
///
/// Registry and path deps contribute to `ResolvedDeps`. Git deps are recorded in the lock only
/// (no fetch or include/lib resolution).
///
/// # Parameters
/// - `config`: Loaded `dcr.toml`.
/// - `_profile` / `_target`: Reserved for future profile/target-specific deps.
/// - `project_root`: Root used to resolve path deps and write `dcr.lock`.
///
/// # Returns
/// Aggregated include/lib/libs, or an error string on resolve/lock failure.
pub fn resolve_deps(
config: &Config,
_profile: &str,
@@ -57,6 +71,7 @@ pub fn resolve_deps(
let mut lock_packages: Vec<DepLock> = Vec::new();
if let Some(deps) = deps_table {
// Process each dependency declaration in the TOML table
for (name, value) in deps {
if register::is_registry_dep(value) {
let pkg_info = register::resolve_package_from_registry(name)?;
@@ -157,6 +172,7 @@ pub fn resolve_deps(
}
}
// Write the lock file with all resolved dependencies
write_lock(
project_root,
&project_name,
@@ -167,11 +183,13 @@ pub fn resolve_deps(
Ok(resolved)
}
/// Git dependency specification (url + optional version/ref for the lockfile).
struct GitDep<'a> {
url: &'a str,
version: Option<String>,
}
/// Parses a git dependency from a TOML value table.
fn git_dep(value: &toml::Value) -> Option<GitDep<'_>> {
if let Some(table) = value.as_table()
&& let Some(url) = table.get("git").and_then(|v| v.as_str())
@@ -185,6 +203,7 @@ fn git_dep(value: &toml::Value) -> Option<GitDep<'_>> {
None
}
/// Extracts the path for a path-based dependency, supporting both table format and legacy string format.
fn path_dep_path(value: &toml::Value) -> Option<&str> {
if let Some(table) = value.as_table() {
return table.get("path").and_then(|v| v.as_str());
@@ -192,12 +211,14 @@ fn path_dep_path(value: &toml::Value) -> Option<&str> {
register::path_from_string_dep(value)
}
/// Adds a directory path to the list if it exists on the filesystem.
fn push_if_exists(paths: &mut Vec<String>, path: &Path) {
if path.exists() {
paths.push(path.to_string_lossy().to_string());
}
}
/// Adds common library directory candidates to the list if they exist.
fn push_default_lib_dirs(paths: &mut Vec<String>, dep_root: &Path) {
for dir in ["lib", "lib64"] {
push_if_exists(paths, &dep_root.join(dir));
@@ -210,6 +231,7 @@ mod tests {
use super::*;
use toml::Value;
/// Tests that path_dep_path correctly handles both TOML table and legacy string inputs for path dependencies.
#[test]
fn path_dep_path_supports_table_and_legacy_strings() {
let table = Value::Table(
@@ -232,6 +254,7 @@ mod tests {
assert_eq!(path_dep_path(&Value::String("1.2.3".to_string())), None);
}
/// Verifies that push_default_lib_dirs includes the target/lib directory when it exists.
#[test]
fn default_lib_dirs_include_packaged_library_output() {
let root = std::env::temp_dir().join(format!(

28
src/core/deps/register.rs
View File

@@ -21,25 +21,30 @@ use std::fs;
use std::path::{Path, PathBuf};
use toml::Value as TomlValue;
/// Represents a registry configuration entry with its URL and priority.
#[derive(Debug, Serialize, Deserialize)]
pub struct Registry {
pub url: String,
pub priority: i32,
}
/// Configuration struct for DCR registries, mapping registry names to Registry details.
#[derive(Debug, Serialize, Deserialize)]
pub struct DcrConfig {
pub registry: std::collections::HashMap<String, Registry>,
}
/// Helper function to get the user's home directory path.
fn home_dir() -> Option<PathBuf> {
crate::utils::fs::home_dir()
}
/// Helper to get the DCR config directory path.
fn dcr_config_dir() -> Option<PathBuf> {
home_dir().map(|h| h.join(".dcr"))
}
/// Loads DCR registry configuration from the TOML file in the user's home directory.
pub fn get_registry_config() -> Option<DcrConfig> {
let home = home_dir()?;
let config_path = home.join(".dcr/config.toml");
@@ -51,6 +56,7 @@ pub fn get_registry_config() -> Option<DcrConfig> {
toml::from_str(&content).ok()
}
/// Returns the path to the registry index file, preferring the DCR_INDEX_PATH env var or falling back to ~/.dcr/index.json.
pub fn get_index_path() -> PathBuf {
std::env::var("DCR_INDEX_PATH")
.map(PathBuf::from)
@@ -61,6 +67,7 @@ pub fn get_index_path() -> PathBuf {
})
}
/// Returns the root directory for registry cache, based on the index path's parent, creating it if necessary.
pub fn get_registry_cache_root() -> PathBuf {
let index_path = get_index_path();
if let Some(parent) = index_path.parent() {
@@ -76,6 +83,7 @@ pub fn get_registry_cache_root() -> PathBuf {
}
}
/// Extracts the package root path from registry info. If the path points to a dcr.toml manifest, returns its parent directory.
pub fn package_root_from_registry_info(pkg_info: &JsonValue) -> Result<PathBuf, String> {
let raw_path = pkg_info
.get("path")
@@ -97,6 +105,7 @@ pub fn package_root_from_registry_info(pkg_info: &JsonValue) -> Result<PathBuf,
Ok(full_path)
}
/// Converts a raw registry path string to a PathBuf, handling file:// prefixes, Windows extended paths, and relative paths by joining to cache root.
pub fn registry_path_to_pathbuf(raw: &str) -> PathBuf {
let s = raw.trim();
if let Some(rest) = s.strip_prefix("file://") {
@@ -130,14 +139,26 @@ pub fn registry_path_to_pathbuf(raw: &str) -> PathBuf {
}
}
/// Returns the include directory path for a dependency root, typically under target/include.
pub fn registry_include_dir(dep_root: &Path) -> PathBuf {
dep_root.join("target").join("include")
}
/// Returns the library directory path for a dependency root, typically under target/lib.
pub fn registry_lib_dir(dep_root: &Path) -> PathBuf {
dep_root.join("target").join("lib")
}
/// Looks up `name` in the local package index (`DCR_INDEX_PATH` / `~/.dcr/index.json`).
///
/// Configured registries are sorted by priority, but the lookup currently always reads the
/// same local index path (per-registry URLs are unused).
///
/// # Parameters
/// - `name`: Package name as in the index.
///
/// # Returns
/// Package JSON object, or an error if config/index is missing or the name is absent.
pub fn resolve_package_from_registry(name: &str) -> Result<JsonValue, String> {
let config = get_registry_config().ok_or("No registry config found")?;
let mut registries: Vec<(&String, &Registry)> = config.registry.iter().collect();
@@ -165,6 +186,10 @@ pub fn resolve_package_from_registry(name: &str) -> Result<JsonValue, String> {
))
}
/// True if the TOML value is a registry-style dependency.
///
/// Strings: not path-like and not git-like. Tables: have version/features/optional/registry
/// and no `git`/`path`/`url` keys.
pub fn is_registry_dep(value: &TomlValue) -> bool {
if let Some(raw) = value.as_str() {
let raw = raw.trim();
@@ -183,6 +208,7 @@ pub fn is_registry_dep(value: &TomlValue) -> bool {
}
}
/// Extracts the path string from a dependency value if it's a path-like dependency.
pub fn path_from_string_dep(value: &TomlValue) -> Option<&str> {
let raw = value.as_str()?.trim();
if let Some(path) = raw.strip_prefix("path:") {
@@ -194,6 +220,7 @@ pub fn path_from_string_dep(value: &TomlValue) -> Option<&str> {
None
}
/// Helper to check if a string represents a local file path.
fn is_path_like_string(raw: &str) -> bool {
raw.starts_with("path:")
|| raw.starts_with("./")
@@ -203,6 +230,7 @@ fn is_path_like_string(raw: &str) -> bool {
|| raw.contains('\\')
}
/// Helper to check if a string represents a git or remote dependency.
fn is_git_like_string(raw: &str) -> bool {
raw.starts_with("git:")
|| raw.starts_with("github:")