• issues详情: https://github.com/d2learn/xlings/issues/104
• pr详情: https://github.com/d2learn/xlings/pull/105

修复代码&测试结果

验证步骤

1.更新xlings到最新版本

irm https://d2learn.org/xlings-install.ps1.txt | iex

2.更新包索引

xim --update index

3.测试

xlings remove code
xlings self clean
xlings install code

预期输出

code@system - already installed

PR: https://github.com/d2learn/xlings/pull/88

xlings帮助信息

xim帮助信息

speak@speak-pc ~> xim

	XIM - Xlings Installation Manager

xim version: pre-v0.0.2

Usage1: $ xlings install [command] [target]
Usage2: $ xim [command] [target]

Commands:
  -i,   install,   install software/package/env
  -r,   remove,    remove the software/package/env
  -u,   update,    update the software/package/env
  -l,   list,      list all installed software/packages/env
  -s,   search,    search for a software/package
  -h,   help,      display this help message

SysCommands:
  --detect,        detect local software/packages
  --update,        update [self | index]
  --add-xpkg,      add xpkg file to index database
  --xpkg-args,     xpkg args
  --add-indexrepo, add indexrepo to repo manager
  --disable-info,  disable info display

Examples:
  xim vscode     -- install vscode
  xim -r vscode  -- remove/uninstall vscode
  xim -l         -- list all installed software/packages
  xim -s code    -- search for software/package with 'code'

More: https://d2learn.org/xlings

d2x帮助信息

d2x version: pre-v0.0.2

Usage: $ d2x [command] [target]

Commands:
	 new,      	 create new d2x project
	 book,     	 open project's book
	 run,      	 run sourcecode file
	 checker,  	 run checker for d2x project's exercises
	 help,     	 help info

More: https://d2learn.org/xlings

大概就是这种的差异

一个简单且通用的版本管理工具 - 支持多版本管理、支持工作空间和环境隔离、支持多版本的命令别名

下载安装

使用xim进行安装

xim --update index
xim -i xvm # 或 xlings install xvm

直接下载

直接下载压缩包&解压出可执行程序

release地址

注: 使用时需要把xvm程序放到一个已经加入PATH的目录里

基本用法

xvm add | 添加程序

支持添加不同版本, 也支持创建命令别名

# xvm add [target] [version] --path [bin-path] --alias [command/bin-file]
xvm add python 2.7.18 --path python2_dir --alias python2
xvm add python 3.12.3 --path python3_dir --alias python3.12
xvm add pv 0.0.1 --alias "python --version"

• target: 生效时可以使用的命令
• version: 这个是标识target的版本号, 建议和应用版本保持一致。如果是别名可以自定义
• --path: 程序所在的实际路径(可选)
• --alias: 在"所设置的路径"下实际执行的命令(可选), 默认为target

注: 默认第一次添加的版本作为全局工作空间的默认版本

xvm list | 查询程序的所有版本

支持模糊查询

# xvm list [target]
xvm list python
xvm list p

xvm use | 切换版本

可以切换到对应的版本, 版本号支持模糊匹配

# xvm use [target] [version]
xvm use python 3.12.3
xvm use python 2   # -> 2.7.18

xvm current | 查询当前版本

支持模糊匹配

# xvm current [target]
xvm current p

xvm remove | 移除之前被添加的程序

这里的移除只是从xvm的版本数据库中删除记录

# xvm remove [target] [version]
xvm remove pv 0.0.1

工作空间和环境隔离

目前xvm支持基于目录的工作空间, 可以和全局工作空间进行隔离(默认有一个全局工作空间)

基础命令

创建工作空间

# xvm workspace [target]
xvm workspace test

注: 工作空间, 默认时激活和继承全局工作空间版本情况的

设置当前工作空间激活状态

当工作空间未激活时就会使用默认的全局空间, 激活时会覆盖全局空间

# xvm workspace [target]
xvm workspace test --active false
xvm workspace test --active true

设置当前工作空间是否继承全局空间

# xvm workspace [target]
xvm workspace test --inherit false
xvm workspace test --inherit true

使用场景

在指定目录创建工作空间, 使用特定的版本

# 假设全局空间中python使用的版本是3
xvm workspace test # 创建工作空间
xvm use python 2   # 切换python版本
xvm current python # 查询当前版本
python --version   # 验证 - python2
cd ..
python --version   # 返回上级目录/版本会自动切换到全局版本python3

其他

临时关闭xvm版本管理功能

通过设置全局workspace的状态, 可以控制xvm的版本管理是否生效

xvm workspace global --active false
xvm workspace global --active true

image.png

基础信息 | Basic Info

• 名称: project-graph
• 协议: mit license
• 简介: 快速绘制节点图的桌面工具，可以用于项目进程拓扑图绘制、快速头脑风暴草稿
• 主页: https://project-graph.top
• 仓库地址: https://github.com/LiRenTech/project-graph
• 支持平台: windows / linux / macos
• d2learn交流版块: https://forum.d2learn.org/category/16/project-graph

XPackage's Pull-Request

• #9

本地测试信息 | Local Test Info

Paste your test console information or picture here (note: xpakcage is your xpackage's filename

ubuntu测试

windows测试 | archlinux测试

step1: xim --add-xpkg yourPath/xpackage.lua

test add to pkgindex database for xpackage

ubuntu

step2: xim -s xpackage

test search for xpackage

ubuntu

[xlings:xim]: search for *project-graph* ...

{ 
  "project-graph@1.0.0" = { },
  "project-graph@nightly" = { },
  "project-graph@1.1.0" = { 
    "project-graph@latest",
    "project-graph" 
  } 
}

step3: xim -i xpackage

test install for xpackage

ubuntu

step4: xim -i xpackage

test installed for xpackage

step5: xim -l xpackage

test list for xpackage

speak@speak-pc:~/workspace/github/d2learn/xim-pkgindex$ xim -l project-graph
-> project-graph@1.1.0 (project-graph@latest, project-graph)

step6: xim -r xpackage

test remove/uninstall for xpackage

step7: xim -r xpackage

test uninstalled for xpackage

目录

• 第一步: 创建个Add XPackage & 填写基础信息
• 第二步: 复制一份包模板文件
• 第三步: 修改文件名和包内容 (可以参考仓库中的包或xpackage规范示例)
• 第四步: 对包内容进行测试
  • 添加包到索引数据库: xim --add-xpkg yourLocalPath/filename.lua
  • 搜索测试: xim -s filename
  • 安装测试: xim -i filename
  • 已经安装测试: xim -i filename (会显示包已安装)
  • 安装列表测试: xim -l filename
  • 卸载测试: xim -r filename
  • 已卸载测试: xim -r filename (会显示包没有安装)
• 第五步: 当第四步通过后, 把测试信息补充到第一步中创建的问题里
• 第六步: fork项目, 并把包文件放到pkgs目录下的对应位置
• 第七步: 发起合入Pull-Request, 把PR地址补充到问题里并在评论区@项目维护人员
• 第八步: TODO (reviewer本地验证&approval)

xlings开源仓库: https://github.com/d2learn/xlings
xim包索引仓库: https://github.com/d2learn/xim-pkgindex

第一步 - 创建一个Add XPackage

在xim-pkgindex的issues创建选择界面选择Add XPackage模板并先填写包的基础信息

• 包名
• 包的简短描述
• 主页
• 开源 or 闭源
• 仓库
• 协议
• ...

第二步: 复制一份包模板文件

复制一份包模板文件。一个包文件有两大部分组成: package + hooks/actions, 并且包文件的语法对应的就是lua语言的基础语法(并不需要特殊学习lua, 只要参考已有的包里的用法即可)

package域

基础信息描述部分

基础信息部分主要是要来描述和记录这个包的相关信息的。**这些信息会在安装的时候进行显示, 但是他们不会实质的影响安装的过程。**但为了包的完整度应该尽可能的填写相关字段(至少包含name、description、type、keywords)。具体格式如下:

package = {
    -- base info
    homepage = "https://example.com",

    name = "package-name",
    description = "Package description",

    authors = "Author Name",
    maintainers = "Maintainer Name or url",
    contributors = "Contributor Name or url",
    license = "MIT",
    repo = "https://example.com/repo",
    docs = "https://example.com/docs",

    -- xim pkg info
    type = "package", -- package, auto-config
    archs = {"x86_64"},
    status = "stable", -- dev, stable, deprecated
    categories = {"category1", "category2"},
    keywords = {"keyword1", "keyword2"},
    date = "2024-12-01",
    --...
}

平台&依赖&资源描述部分 - xpm

xpm字段描述了这个包支持的具体的平台, 以及每个平台上安装这个包需要的依赖和网络资源。这个部分会实质性的影响安装过程且没有描述的平台/系统和版本将不会添加到用户的本地索引数据库中, 即不可查询和安装

• 系统名是xpm的中的key, 表示要支持的系统/平台
• 系统key对应的值包含:
  • deps是可选项, 用来描述这个包在对应平台下需要的依赖(这些依赖需要已经在索引仓库中)
  • 版本项也是kv结构 ["key"] = {"url", "sha256"}
    • 它的key的格式一般为x.x.x其中x是数字, 也可以用latest描述(用户默认安装的版本)
    • 它的值的格式为一对字符串, 第一个是网络资源url, 第二个为这个资源对应的sha256校验码(为可选项, xim会自动的下载资源并校验, 路径会存在pkginfo.install_file中)
• 在xpm的中系统字段和版本字段支持同级引用, 如: ["latest"] = { ref = "1.0.1"} latest对应的值将会是1.0.1里的值

package = {
    -- ...
    xpm = {
        windows = {
            deps = {"dep1", "dep2"},
            ["1.0.1"] = {"url", "sha256"},
            ["1.0.0"] = {"url", "sha256"},
        },
        ubuntu = {
            deps = {"dep3", "dep4"},
            ["latest"] = { ref = "1.0.1"},
            ["1.0.1"] = {"url", "sha256"},
            ["1.0.0"] = {"url", "sha256"},
        },
    },
}

注:

1.latest版本一般会使用ref引用到一个具体的版本上

2.如果没有网络资源时(例如是auto-config包)可以填写一个空列表。如: ["1.0.1"] = { },

hooks/actions域

hooks域主要是安装或卸载时实际对应的lua函数, 最少要包含: installed、install、uninstall 这三个函数, 他们描述了包对应动作下的具体行为。

installed

用来检测对应版本是否被安装, 支持返回true/false或直接返回包含版本的字符串, 框架中会自动的检测字符串是否包含对应的版本号, 常用的实现是直接返回 os.iorun("program --version")。对于无法直接获取版本号的包/软件, 可以通过代码自行判断并和当前要执行的版本号进行对比, 然后返回true或false

function installed()
    -- ...
end

install/uninstall

install和uninstall主要是对应的安装和卸载, 可以使用lua代码对资源文件进行操作。通常使用os.exec函数等同与命令行

注: 所有的hooks都运行在和所下载资源的同级目录

第三步: 修改文件名和包内容 - mdbook包文件示例

把包模板文件重命令为mdbook.lua并修改文件内容

mdbook安装的核心逻辑是, 把解压出来的执行文件复制到系统的bin目录或其他已经添加到path环境变量中的路径里

添加mdbook基础信息

package = {
    -- base info
    name = "mdbook",
    description = "Create book from markdown files. Like Gitbook but implemented in Rust",

    authors = "Mathieu David, Michael-F-Bryan, Matt Ickstadt",
    contributors = "https://github.com/rust-lang/mdBook/graphs/contributors",
    license = "MPL-2.0",
    repo = "https://github.com/rust-lang/mdBook",
    docs = "https://rust-lang.github.io/mdBook",

    -- xim pkg info
    type = "package",
    categories = {"book", "markdown"},
    keywords = {"book", "gitbook", "rustbook", "markdown"},
}

添加xpm基础信息

• 主要支持平台为: windows, linux(ubuntu, debian, archlinux)
• mdbook没有依赖, 所以不需要deps字段
• 把mdbook的不同平台的二进制执行文件包的url添加到对应版本的value中
• windows支持0.4.40, debain支持0.4.40, 0.4.43版本
• 设置每个平台下的latest版本对应的具体版本, windows上ref到0.4.40, debain上ref到0.4.43
• 由于mdbook支持所有linux系统, 所以ubuntu, archlinux可以直接ref到debian

package = {
    -- ...
    xpm = {
        windows = {
            ["latest"] = { ref = "0.4.40" },
            ["0.4.40"] = {
                url = "https://gitee.com/sunrisepeak/xlings-pkg/releases/download/mdbook/mdbook-v0.4.40-x86_64-pc-windows-msvc.zip",
                sha256 = nil
            }
        },
        debain = {
            ["latest"] = { ref = "0.4.43" },
            ["0.4.43"] = {
                url = "https://github.com/rust-lang/mdBook/releases/download/v0.4.43/mdbook-v0.4.43-x86_64-unknown-linux-gnu.tar.gz",
                sha256 = "d20c2f20eb1c117dc5ebeec120e2d2f6455c90fe8b4f21b7466625d8b67b9e60"
            },
            ["0.4.40"] = {
                url = "https://github.com/rust-lang/mdBook/releases/download/v0.4.40/mdbook-v0.4.40-x86_64-unknown-linux-gnu.tar.gz",
                sha256 = "9ef07fd288ba58ff3b99d1c94e6d414d431c9a61fdb20348e5beb74b823d546b"
            },
        },
        archlinux = { ref = "debain" },
        ubuntu = { ref = "debain" },
    },
}

编写mdbook的hooks函数

• 使用import语法导入xim的platform模块, 用于获取系统的bin目录
• 由于mdbook的压缩包解压出来就是一个mdbook的可执行文件, windows上为mdbook.exe, linux上为mdbook。所以使用lua语法定义局部变量mdbook_file用于表示不同平台下的对应的文件名
• 实现installed函数: mdbook本身可以用mdbook --version查询当前版本, 所以这里就执行返回os.iorun("mdbook --version")这个命令运行后的字符串就可以了
• 实现install函数: 并且xim的框架会自动的解压下载的压缩包, 所以实际的安装就是复制这个可执行文件到bin目录
• 实现uninstall函数: 同理卸载mdbook, 就是直接把这个文件删除

-- package...

import("platform")

local bindir = platform.get_config_info().bindir

local mdbook_file = {
    windows = "mdbook.exe",
    linux = "mdbook",
}

function installed()
    return os.iorun("mdbook --version")
end

function install()
    os.cp(mdbook_file[os.host()], bindir)
    return true
end

function uninstall()
    os.tryrm(path.join(bindir, mdbook_file[os.host()]))
    return true
end

注: 更多复杂的包文件实现, 可以参考索引仓库中的其他包文件

第四步: 对包内容进行测试

通过把包文件添加到索引数据库进行相关操作的测试和验证

添加包到索引数据库

xim --add-xpkg yourLocalPath/mdbook.lua

示例

speak@speak-pc:~$ xim --add-xpkg mdbook.lua
[xlings:xim]: convert xpkg-file to runtime path - mdbook.lua
[xlings:xim]: add xpkg - /home/speak/mdbook.lua
[xlings:xim]: update index database

搜索测试

检测是是否能正常显示包可安装的版本

xim -s mdbook

示例

speak@speak-pc:~$ xim -s mdbook
[xlings:xim]: search for *mdbook* ...

{ 
  "mdbook@0.4.40" = { },
  "mdbook@0.4.43" = { 
    "mdbook",
    "mdbook@latest" 
  } 
}

安装测试

执行包的安装命令测试资源和hooks函数是否正常执行

xim -i mdbook

示例

speak@speak-pc:~$ xim -i mdbook
[xlings:xim]: create pm executor for mdbook ... 

--- [package] info

name: mdbook
version: 0.4.43
authors: Mathieu David, Michael-F-Bryan, Matt Ickstadt
contributors: https://github.com/rust-lang/mdBook/graphs/contributors
license: MPL-2.0
repo: https://github.com/rust-lang/mdBook
docs: https://rust-lang.github.io/mdBook

	Create book from markdown files. Like Gitbook but implemented in Rust

-> install mdbook? (y/n)

命令会执行如下动作

• installed
• download - 不需要实现
• build - 可选
• install
• config - 可选

安装完成后可以, 重新打开一个窗口(刷新环境), 再次运行安装看是否会重复安装

安装列表测试

执行list命令, 查看被安装的版本是否正确

xim -l mdbook

speak@speak-pc:~$ xim -l mdbook
-> mdbook@0.4.43 (mdbook@latest, mdbook)

卸载测试

测试卸载功能

xim -r mdbook

示例

speak@speak-pc:~$ xim -r mdbook
[xlings:xim]: create pm executor for mdbook ... 

--- [package] info

name: mdbook
version: 0.4.43
authors: Mathieu David, Michael-F-Bryan, Matt Ickstadt
contributors: https://github.com/rust-lang/mdBook/graphs/contributors
license: MPL-2.0
repo: https://github.com/rust-lang/mdBook
docs: https://rust-lang.github.io/mdBook

	Create book from markdown files. Like Gitbook but implemented in Rust

-> uninstall/remove mdbook? (y/n)
y
xxx
[xlings:xim]: mdbook - removed

	     反馈 & 交流 | Feedback & Discourse
	(if encounter any problem, please report it)

	https://forum.d2learn.org/category/9/xlings
	https://github.com/d2learn/xlings/issues

[xlings:xim]: update index database

同理, 卸载后可以在此执行卸载命令进行测试是否能检测到包已经被卸载

第五步: 把测试信息补充到第一步中创建的问题里

把第四步中测试的log或则截图补充到第一步创建的issue里

第六步: 索引仓库和包文件位置

fork包索引仓库xim-pkgindex, 并把包文件放到pkgs目录下的对应字母目录

索引仓库是按文件名的首字母进行分类的

第七步: 发起合入请求

• 先把添加的文件提交到自己fork的仓库
• 发起合入的Pull-Request
• 把PR地址补充到问题里
• 在评论区@项目维护人员

第八步: TODO (reviewer本地验证&approval)

交流讨论 & 验证通过后合入仓库

第九步: 更新本地索引数据库

xim会自动同步最新的包索引数据库到本地, 然后就可以对该包进行管理了

xim --update index

快速绘制节点图的桌面工具，可以用于项目进程拓扑图绘制、快速头脑风暴草稿

一键安装命令

xlings install project-graph

基础信息

name: Project Graph
homepage: https://liren.zty012.de/project-graph
author: LiRenTech Team
licenses: MIT
github: https://github.com/LiRenTech/project-graph

        快速绘制节点图的桌面工具，可以用于项目进程拓扑图绘制、快速头脑风暴草稿

Ref

• https://github.com/d2learn/xlings/issues/23
• https://github.com/d2learn/xlings/blob/main/core/installer/project_graph.lua

WSL - Windows Subsystem for Linux

Windows系统中的Linux子系统

一键安装命令

xlings install wsl

基础信息

name: wsl
homepage: https://learn.microsoft.com/windows/wsl
author: Microsoft
licenses: MIT
github: https://github.com/microsoft/WSL
docs: https://learn.microsoft.com/windows/wsl

        Windows Subsystem for Linux lets developers run a GNU/Linux environment directly on Windows

Other

• https://github.com/d2learn/xlings/blob/main/core/installer/windows/wsl.lua

增加windows安装器模块

把只支持windows系统的软件/环境放到windows目录, 通过加载器来自动加载

commit

https://github.com/d2learn/xlings/commit/8cd1491cbbcec3eca51b51232209eb0f5dd59248

• 开源仓库: https://github.com/d2learn/xlings
• 工具介绍页: https://d2learn.org/xlings
• 工具文档: https://d2learn.org/docs/xlings
• 常见问题汇总: http://forum.d2learn.org/post/112

快速安装

在命令行窗口执行一键安装命令

Linux

curl -fsSL https://d2learn.org/xlings-install.sh | bash

or

wget https://d2learn.org/xlings-install.sh -O - | bash

Windows - PowerShell

Invoke-Expression (Invoke-Webrequest 'https://d2learn.org/xlings-install.ps1.txt' -UseBasicParsing).Content

一个技术知识分享、学习、交流的开源社区。社区以d2learn动手学(从实践出发)为理念和BOOK + CODE + VIDEO + X的结构, 进行各种技术教程、代码实验、课程教学等相关项目的开发。并对这套框架进行抽象和汇总形成了基础工具xlings, 来支撑类d2x项目的快速搭建和管理, 提供:练习代码自动检测、AI智能提示引导、常用技术软件/工具便捷下载、项目模板、项目包管理、Markdown书籍等通用功能

近期活跃项目

• xlings : 一个用于技术学习、软件安装、教程教学类项目搭建和管理的基础工具
• d2ds : 动手学数据结构项目
• d2python : 动手学Python项目

参与社区讨论和贡献

论坛/交流

• 即时交流群(Q): 167535744
• 各项目issues: 对应项目的问题/Bug反馈、功能请求
• d2learn综合社区: 代码/经验分享、社区发展、想法交流等社区相关问题

参与开发和维护

• 解答社区中用户的问题
• 修复项目Bug, 完善项目文档
• 参与新功能和新模块的开发
• 创建新的类d2x项目

如果你有好的项目想法, 欢迎和社区维护者进行交流讨论哦

课程主页 - 社区文档 - 社区论坛 - issues看板 - 项目开发看板