refactor: update Taskfile and documentation for LanceDB build commands

2026-07-24 15:03:45 +08:00
parent e2a76ef54a
commit 4067bdb4bb
3 changed files with 117 additions and 112 deletions
@@ -188,9 +188,9 @@ Default development URLs:
 ```bash
 task dev        # start backend and frontend development servers
 task build      # build the frontend SPA and current-platform Go binary into dist/
-task build LANCEDB=1  # build the current-platform LanceDB binary into dist/
+task build:lancedb  # build the current-platform LanceDB binary into dist/
 task release    # build linux/darwin/windows release binaries into dist/
-task release LANCEDB=1  # build LanceDB release binaries into dist/
+task release:lancedb  # build LanceDB release binaries into dist/
 task generator  # run code generation
 task enums      # generate frontend enums
 task --list     # show available tasks
@@ -188,9 +188,9 @@ task dev
 ```bash
 task dev            # 同时启动后端和前端开发服务
 task build          # 构建前端 SPA 和当前平台 Go 二进制
-task build LANCEDB=1  # 构建当前平台 LanceDB 二进制
+task build:lancedb  # 构建当前平台 LanceDB 二进制
 task release        # 构建常用平台二进制
-task release LANCEDB=1  # 构建 LanceDB 发布二进制
+task release:lancedb  # 构建 LanceDB 发布二进制
 task generator      # 执行代码生成
 task enums          # 生成前端枚举
 task --list         # 查看可用任务
@@ -1,5 +1,7 @@
 version: '3'

+silent: true
+
 vars:
  APP: agent-desk
  MAIN: ./cmd/server
@@ -17,31 +19,13 @@ vars:
    sh: 'printf "%s" "${LANCEDB_VERSION:-v0.1.2}"'
  LANCEDB_DOWNLOAD_SCRIPT:
    sh: 'printf "%s" "${LANCEDB_DOWNLOAD_SCRIPT:-https://raw.githubusercontent.com/lancedb/lancedb-go/main/scripts/download-artifacts.sh}"'
-  LANCEDB:
-    sh: 'printf "%s" "${LANCEDB:-0}"'
-  UNAME_S:
+  HOST_OS:
    sh: uname -s
-  UNAME_M:
+  HOST_ARCH:
    sh: uname -m
-  BUILD_OUTPUT:
-    sh: |
-      suffix=""
-      ext=""
-      if [ "{{.LANCEDB}}" = "1" ]; then
-        suffix="-lancedb"
-      fi
-      if [ "$(${GO:-go} env GOOS)" = "windows" ]; then
-        ext=".exe"
-      fi
-      printf "%s/%s%s%s" "{{.DIST_DIR}}" "{{.APP}}" "$suffix" "$ext"
-  LANCEDB_ARCH:
-    sh: |
-      case "$(uname -m)" in
-        x86_64|amd64) printf amd64 ;;
-        arm64|aarch64) printf arm64 ;;
-        *) printf unsupported ;;
-      esac
-  LANCEDB_PLATFORM:
+  HOST_GOOS:
+    sh: '${GO:-go} env GOOS'
+  HOST_LANCEDB_PLATFORM:
    sh: |
      case "$(uname -s)" in
        Darwin) printf darwin ;;
@@ -49,7 +33,14 @@ vars:
        MINGW*|MSYS*|CYGWIN*) printf windows ;;
        *) printf unsupported ;;
      esac
-  LANCEDB_PLATFORM_ARCH:
+  HOST_LANCEDB_ARCH:
+    sh: |
+      case "$(uname -m)" in
+        x86_64|amd64) printf amd64 ;;
+        arm64|aarch64) printf arm64 ;;
+        *) printf unsupported ;;
+      esac
+  HOST_LANCEDB_TARGET:
    sh: |
      case "$(uname -s)" in
        Darwin) platform=darwin ;;
@@ -63,7 +54,7 @@ vars:
        *) arch=unsupported ;;
      esac
      printf "%s_%s" "$platform" "$arch"
-  LANCEDB_NATIVE_LIB:
+  HOST_LANCEDB_LIB:
    sh: |
      case "$(uname -s)" in
        Darwin) platform=darwin ;;
@@ -88,76 +79,85 @@ tasks:
  dev:
    desc: Start backend and frontend development servers
    deps:
-      - task: _go-dev
-      - task: _web-dev
+      - task: dev:backend
+      - task: dev:frontend

  build:
-    desc: Build the current system into dist/; pass LANCEDB=1 for the current-platform LanceDB binary
+    desc: Build the frontend SPA and current-platform Go binary into dist/
+    deps:
+      - task: build:web
+      - task: build:dist
    cmds:
      - |
-        if [ "{{.LANCEDB}}" = "1" ]; then
-          task _lancedb-check
+        ext=""
+        if [ "{{.HOST_GOOS}}" = "windows" ]; then
+          ext=".exe"
        fi
-      - task: _prepare-dist
-      - task: _web-build-spa
+        output="{{.DIST_DIR}}/{{.APP}}${ext}"
+        echo "Building $output..."
+        {{.GO}} build -v -o "$output" {{.MAIN}}
+
+  build:lancedb:
+    desc: Build the current-platform LanceDB binary into dist/
+    deps:
+      - task: lancedb:ensure-current
+      - task: build:web
+      - task: build:dist
+    cmds:
      - |
-        echo "Building {{.BUILD_OUTPUT}}..."
-        if [ "{{.LANCEDB}}" = "1" ]; then
-          case "$(uname -s)" in
-            Darwin) system_ldflags="-framework Security -framework CoreFoundation" ;;
-            Linux) system_ldflags="-lm -ldl -lpthread" ;;
-            *) system_ldflags="" ;;
-          esac
-          CGO_ENABLED=1 CGO_CFLAGS="{{.LANCEDB_CGO_CFLAGS}}" CGO_LDFLAGS="{{.LANCEDB_NATIVE_LIB}} $system_ldflags" \
-            {{.GO}} build -tags lancedb -v -o "{{.BUILD_OUTPUT}}" {{.MAIN}}
-        else
-          {{.GO}} build -v -o "{{.BUILD_OUTPUT}}" {{.MAIN}}
+        case "$(uname -s)" in
+          Darwin) system_ldflags="-framework Security -framework CoreFoundation" ;;
+          Linux) system_ldflags="-lm -ldl -lpthread" ;;
+          *) system_ldflags="" ;;
+        esac
+        ext=""
+        if [ "{{.HOST_GOOS}}" = "windows" ]; then
+          ext=".exe"
        fi
+        output="{{.DIST_DIR}}/{{.APP}}-lancedb${ext}"
+        echo "Building $output..."
+        CGO_ENABLED=1 CGO_CFLAGS="{{.LANCEDB_CGO_CFLAGS}}" CGO_LDFLAGS="{{.HOST_LANCEDB_LIB}} $system_ldflags" \
+          {{.GO}} build -tags lancedb -v -o "$output" {{.MAIN}}

  release:
-    desc: Build linux/darwin/windows release binaries into dist/; pass LANCEDB=1 for LanceDB release binaries
+    desc: Build linux/darwin/windows release binaries into dist/
+    deps:
+      - task: build:web
+      - task: build:dist
    cmds:
-      - |
-        if [ "{{.LANCEDB}}" = "1" ]; then
-          task _lancedb-release-check
-        fi
-      - task: _prepare-dist
-      - task: _web-build-spa
      - |
        echo "Building release binaries in {{.DIST_DIR}}..."
-        if [ "{{.LANCEDB}}" = "1" ]; then
-          if [ ! -f "{{.ROOT_DIR}}/include/lancedb.h" ]; then
-            echo "Missing LanceDB header: {{.ROOT_DIR}}/include/lancedb.h"
-            exit 1
-          fi
-          build_lancedb() {
-            platform="$1"
-            arch="$2"
-            ext="$3"
-            system_ldflags="$4"
-            native_lib="{{.ROOT_DIR}}/lib/${platform}_${arch}/liblancedb_go.a"
-            output="{{.DIST_DIR}}/{{.APP}}-lancedb-${platform}-${arch}${ext}"
-            if [ ! -f "$native_lib" ]; then
-              echo "Missing LanceDB native library for ${platform}/${arch}: $native_lib"
-              echo "LanceDB release builds require matching native artifacts and a CGO-capable toolchain for each target platform."
-              exit 1
-            fi
-            echo "Building $output..."
-            CGO_ENABLED=1 CGO_CFLAGS="-I{{.ROOT_DIR}}/include" CGO_LDFLAGS="$native_lib $system_ldflags" \
-              GOOS="$platform" GOARCH="$arch" {{.GO}} build -tags lancedb -v -o "$output" {{.MAIN}}
-          }
-          build_lancedb linux amd64 "" "-lm -ldl -lpthread"
-          build_lancedb linux arm64 "" "-lm -ldl -lpthread"
-          build_lancedb darwin amd64 "" "-framework Security -framework CoreFoundation"
-          build_lancedb darwin arm64 "" "-framework Security -framework CoreFoundation"
-          build_lancedb windows amd64 ".exe" ""
-        else
-          GOOS=linux GOARCH=amd64 {{.GO}} build -v -o "{{.DIST_DIR}}/{{.APP}}-linux-amd64" {{.MAIN}}
-          GOOS=linux GOARCH=arm64 {{.GO}} build -v -o "{{.DIST_DIR}}/{{.APP}}-linux-arm64" {{.MAIN}}
-          GOOS=darwin GOARCH=amd64 {{.GO}} build -v -o "{{.DIST_DIR}}/{{.APP}}-darwin-amd64" {{.MAIN}}
-          GOOS=darwin GOARCH=arm64 {{.GO}} build -v -o "{{.DIST_DIR}}/{{.APP}}-darwin-arm64" {{.MAIN}}
-          GOOS=windows GOARCH=amd64 {{.GO}} build -v -o "{{.DIST_DIR}}/{{.APP}}-windows-amd64.exe" {{.MAIN}}
-        fi
+        GOOS=linux GOARCH=amd64 {{.GO}} build -v -o "{{.DIST_DIR}}/{{.APP}}-linux-amd64" {{.MAIN}}
+        GOOS=linux GOARCH=arm64 {{.GO}} build -v -o "{{.DIST_DIR}}/{{.APP}}-linux-arm64" {{.MAIN}}
+        GOOS=darwin GOARCH=amd64 {{.GO}} build -v -o "{{.DIST_DIR}}/{{.APP}}-darwin-amd64" {{.MAIN}}
+        GOOS=darwin GOARCH=arm64 {{.GO}} build -v -o "{{.DIST_DIR}}/{{.APP}}-darwin-arm64" {{.MAIN}}
+        GOOS=windows GOARCH=amd64 {{.GO}} build -v -o "{{.DIST_DIR}}/{{.APP}}-windows-amd64.exe" {{.MAIN}}
+
+  release:lancedb:
+    desc: Build LanceDB release binaries into dist/
+    deps:
+      - task: lancedb:check-release
+      - task: build:web
+      - task: build:dist
+    cmds:
+      - |
+        echo "Building LanceDB release binaries in {{.DIST_DIR}}..."
+        build_lancedb() {
+          platform="$1"
+          arch="$2"
+          ext="$3"
+          system_ldflags="$4"
+          native_lib="{{.ROOT_DIR}}/lib/${platform}_${arch}/liblancedb_go.a"
+          output="{{.DIST_DIR}}/{{.APP}}-lancedb-${platform}-${arch}${ext}"
+          echo "Building $output..."
+          CGO_ENABLED=1 CGO_CFLAGS="-I{{.ROOT_DIR}}/include" CGO_LDFLAGS="$native_lib $system_ldflags" \
+            GOOS="$platform" GOARCH="$arch" {{.GO}} build -tags lancedb -v -o "$output" {{.MAIN}}
+        }
+        build_lancedb linux amd64 "" "-lm -ldl -lpthread"
+        build_lancedb linux arm64 "" "-lm -ldl -lpthread"
+        build_lancedb darwin amd64 "" "-framework Security -framework CoreFoundation"
+        build_lancedb darwin arm64 "" "-framework Security -framework CoreFoundation"
+        build_lancedb windows amd64 ".exe" ""

  generator:
    desc: Run code generation
@@ -169,51 +169,55 @@ tasks:
    cmds:
      - '{{.GO}} run ./cmd/enums/generator.go'

-  _web-build-spa:
+  dev:backend:
+    internal: true
    cmds:
-      - 'cd {{.WEB_DIR}} && {{.PNPM}} build:sdk && {{.PNPM}} build'
-
-  _web-dev:
-    cmds:
-      - 'cd {{.WEB_DIR}} && NEXT_PUBLIC_API_BASE_URL="" NEXT_API_BASE_URL="{{.DEV_API_BASE_URL}}" {{.PNPM}} dev'
-
-  _go-dev:
-    cmds:
-      - task: _lancedb-check
+      - task: lancedb:ensure-current
      - |
+        echo "Starting backend on http://127.0.0.1:{{.DEV_PORT}} ..."
        case "$(uname -s)" in
          Darwin) system_ldflags="-framework Security -framework CoreFoundation" ;;
          Linux) system_ldflags="-lm -ldl -lpthread" ;;
          *) system_ldflags="" ;;
        esac
-        AGENT_DESK_SERVER_PORT="{{.DEV_PORT}}" CGO_ENABLED=1 CGO_CFLAGS="{{.LANCEDB_CGO_CFLAGS}}" CGO_LDFLAGS="{{.LANCEDB_NATIVE_LIB}} $system_ldflags" \
+        AGENT_DESK_SERVER_PORT="{{.DEV_PORT}}" CGO_ENABLED=1 CGO_CFLAGS="{{.LANCEDB_CGO_CFLAGS}}" CGO_LDFLAGS="{{.HOST_LANCEDB_LIB}} $system_ldflags" \
          {{.GO}} run -tags "dev lancedb" {{.MAIN}}

-  _prepare-dist:
+  dev:frontend:
+    internal: true
+    cmds:
+      - |
+        echo "Starting frontend on http://localhost:3000 ..."
+        cd {{.WEB_DIR}} && NEXT_PUBLIC_API_BASE_URL="" NEXT_API_BASE_URL="{{.DEV_API_BASE_URL}}" {{.PNPM}} dev
+
+  build:web:
+    internal: true
+    cmds:
+      - 'cd {{.WEB_DIR}} && {{.PNPM}} build:sdk && {{.PNPM}} build'
+
+  build:dist:
+    internal: true
    cmds:
      - 'mkdir -p {{.DIST_DIR}}'

-  _lancedb-artifacts:
+  lancedb:ensure-current:
+    internal: true
    cmds:
      - |
-        if [ "{{.LANCEDB_PLATFORM}}" = "unsupported" ] || [ "{{.LANCEDB_ARCH}}" = "unsupported" ]; then
-          echo "Unsupported LanceDB platform: {{.UNAME_S}}/{{.UNAME_M}}"
+        if [ "{{.HOST_LANCEDB_PLATFORM}}" = "unsupported" ] || [ "{{.HOST_LANCEDB_ARCH}}" = "unsupported" ]; then
+          echo "Unsupported LanceDB platform: {{.HOST_OS}}/{{.HOST_ARCH}}"
          exit 1
        fi
      - |
-        if [ -f "{{.LANCEDB_NATIVE_LIB}}" ] && [ -f "{{.ROOT_DIR}}/include/lancedb.h" ]; then
-          echo "LanceDB native artifacts already exist for {{.LANCEDB_PLATFORM_ARCH}}."
+        if [ -f "{{.HOST_LANCEDB_LIB}}" ] && [ -f "{{.ROOT_DIR}}/include/lancedb.h" ]; then
+          echo "LanceDB native artifacts already exist for {{.HOST_LANCEDB_TARGET}}."
        else
-          echo "Downloading LanceDB native artifacts {{.LANCEDB_VERSION}} for {{.LANCEDB_PLATFORM_ARCH}}..."
+          echo "Downloading LanceDB native artifacts {{.LANCEDB_VERSION}} for {{.HOST_LANCEDB_TARGET}}..."
          curl -sSL "{{.LANCEDB_DOWNLOAD_SCRIPT}}" | bash -s "{{.LANCEDB_VERSION}}"
        fi
-
-  _lancedb-check:
-    cmds:
-      - task: _lancedb-artifacts
      - |
-        if [ ! -f "{{.LANCEDB_NATIVE_LIB}}" ]; then
-          echo "Missing LanceDB native library: {{.LANCEDB_NATIVE_LIB}}"
+        if [ ! -f "{{.HOST_LANCEDB_LIB}}" ]; then
+          echo "Missing LanceDB native library: {{.HOST_LANCEDB_LIB}}"
          exit 1
        fi
      - |
@@ -222,7 +226,8 @@ tasks:
          exit 1
        fi

-  _lancedb-release-check:
+  lancedb:check-release:
+    internal: true
    cmds:
      - |
        if [ ! -f "{{.ROOT_DIR}}/include/lancedb.h" ]; then