diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index f16cdae4a..dc5bb4d3f 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -23,11 +23,10 @@ -- [ ] `pnpm check` 通过 -- [ ] `cargo check --no-default-features` 通过 +- [ ] `make check` 通过 +- [ ] `make cargo-check-fast` 通过 - [ ] 相关测试通过 ## 关联 Issue - diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7891ee181..2edc1df65 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,25 +19,33 @@ Required tools: - Node.js `>=22.13.0` - pnpm `10.27.0` +- Make - Rust stable - Java 17, when working on JDBC plugin packaging Install dependencies: ```bash -pnpm install +make install ``` Run the desktop app during development: ```bash -pnpm dev:tauri +make ``` -Run the web backend: +Run the web app during development: ```bash -pnpm dev:backend +make dev-web # frontend +make dev-backend # backend +``` + +Preview the documentation site: + +```bash +make docs ``` ## Checks @@ -45,7 +53,7 @@ pnpm dev:backend Before opening a pull request, run: ```bash -pnpm check +make check cargo fmt --check cargo check --workspace --locked ``` @@ -55,9 +63,9 @@ cargo check --workspace --locked > development when you're not touching DuckDB features: > > ```bash -> cargo check --workspace --no-default-features -> cargo test --workspace --no-default-features -> pnpm tauri dev -- --no-default-features +> make cargo-check-fast +> make cargo-test-fast +> make dev-fast > ``` > > Release builds and CI should always include DuckDB (omit the flag). diff --git a/Makefile b/Makefile new file mode 100644 index 000000000..620a5e389 --- /dev/null +++ b/Makefile @@ -0,0 +1,90 @@ +.DEFAULT_GOAL := dev + +PNPM ?= pnpm +TAURI_DEV_PORT ?= 1420 + +.PHONY: help install docs-install check-tauri-dev-port dev dev-fast dev-web dev-backend build package docs docs-build check test cargo-check-fast cargo-test-fast + +node_modules/.modules.yaml: package.json pnpm-lock.yaml + $(PNPM) install --frozen-lockfile + +docs/node_modules/.modules.yaml: docs/package.json docs/pnpm-lock.yaml + cd docs && $(PNPM) install --frozen-lockfile --ignore-workspace + +help: + @printf '%s\n' 'DBX development targets:' + @printf '%s\n' '' + @printf '%s\n' 'App:' + @printf ' %-23s %s\n' 'make' 'Start the local desktop development environment' + @printf ' %-23s %s\n' 'make dev' 'Start the local desktop development environment' + @printf ' %-23s %s\n' 'make dev-fast' 'Start Tauri dev without default Rust features' + @printf ' %-23s %s\n' 'make dev-web' 'Start the web frontend development server' + @printf ' %-23s %s\n' 'make dev-backend' 'Start the web backend development server' + @printf ' %-23s %s\n' 'make build' 'Run type checks and build the desktop frontend' + @printf ' %-23s %s\n' 'make package' 'Build the desktop app package' + @printf '%s\n' '' + @printf '%s\n' 'Docs:' + @printf ' %-23s %s\n' 'make docs' 'Start the documentation site development server' + @printf ' %-23s %s\n' 'make docs-build' 'Build the documentation site' + @printf ' %-23s %s\n' 'make docs-install' 'Install documentation site dependencies' + @printf '%s\n' '' + @printf '%s\n' 'Checks:' + @printf ' %-23s %s\n' 'make check' 'Run project checks' + @printf ' %-23s %s\n' 'make test' 'Run project tests' + @printf ' %-23s %s\n' 'make cargo-check-fast' 'Run Rust check without default features' + @printf ' %-23s %s\n' 'make cargo-test-fast' 'Run Rust tests without default features' + @printf '%s\n' '' + @printf '%s\n' 'Setup:' + @printf ' %-23s %s\n' 'make install' 'Install root project dependencies' + +install: + $(PNPM) install --frozen-lockfile + +docs-install: + cd docs && $(PNPM) install --frozen-lockfile --ignore-workspace + +check-tauri-dev-port: + @if lsof -nP -iTCP:$(TAURI_DEV_PORT) -sTCP:LISTEN >/dev/null 2>&1; then \ + echo "Port $(TAURI_DEV_PORT) is already in use. DBX Tauri dev requires http://localhost:$(TAURI_DEV_PORT)."; \ + echo ""; \ + lsof -nP -iTCP:$(TAURI_DEV_PORT) -sTCP:LISTEN; \ + echo ""; \ + echo "Stop the process above, then run make dev again. Example: kill "; \ + exit 1; \ + fi + +dev: node_modules/.modules.yaml check-tauri-dev-port + $(PNPM) dev:tauri + +dev-fast: node_modules/.modules.yaml check-tauri-dev-port + $(PNPM) tauri dev -- --no-default-features + +dev-web: node_modules/.modules.yaml + $(PNPM) dev:web + +dev-backend: node_modules/.modules.yaml + $(PNPM) dev:backend + +build: node_modules/.modules.yaml + $(PNPM) build:checked + +package: node_modules/.modules.yaml + $(PNPM) tauri build + +docs: docs/node_modules/.modules.yaml + cd docs && ./node_modules/.bin/next dev --hostname 127.0.0.1 + +docs-build: docs/node_modules/.modules.yaml + cd docs && ./node_modules/.bin/next build && node scripts/generate-sitemap.mjs + +check: node_modules/.modules.yaml + $(PNPM) check + +test: node_modules/.modules.yaml + $(PNPM) test + +cargo-check-fast: + cargo check --no-default-features + +cargo-test-fast: + cargo test --no-default-features diff --git a/README.md b/README.md index 2974988e5..ffe46057a 100644 --- a/README.md +++ b/README.md @@ -246,21 +246,22 @@ No additional dependencies required. ### Development ```bash -pnpm install -pnpm dev:tauri +make ``` +`make` installs root dependencies when needed and starts the local Tauri desktop development environment. + > [!TIP] > DuckDB compilation takes a while. If you're not working on DuckDB features, > skip it to speed up local builds: > > ```bash > # Fast checks (skip DuckDB) -> cargo check --no-default-features -> cargo test --no-default-features +> make cargo-check-fast +> make cargo-test-fast > > # Tauri dev without DuckDB -> pnpm tauri dev -- --no-default-features +> make dev-fast > ``` > > The `--no-default-features` flag only affects local development. @@ -269,10 +270,18 @@ pnpm dev:tauri Web version: ```bash -pnpm dev:web # frontend -pnpm dev:backend # backend +make dev-web # frontend +make dev-backend # backend ``` +Documentation site: + +```bash +make docs +``` + +The official DBX documentation site lives in `docs/`. If you want to improve the website content or documentation pages, edit the files under `docs/` and run `make docs` to preview the site locally. + JDBC agent driver development projects live in `agents/`: ```bash @@ -285,7 +294,7 @@ Build artifacts from `agents/drivers//build/libs/` are picked up by loc ### Build ```bash -pnpm tauri build +make package ``` The installer will be in `src-tauri/target/release/bundle/`. diff --git a/README.zh-CN.md b/README.zh-CN.md index 1494c1054..630fa23ea 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -247,20 +247,21 @@ sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev libappindicator3-dev ### 开发 ```bash -pnpm install -pnpm dev:tauri +make ``` +`make` 会在需要时安装根目录依赖，并启动本地 Tauri 桌面端开发环境。 + > [!TIP] > DuckDB 从源码编译较慢。如果不涉及 DuckDB 功能，可以跳过以加速本地构建： > > ```bash > # 快速检查（跳过 DuckDB） -> cargo check --no-default-features -> cargo test --no-default-features +> make cargo-check-fast +> make cargo-test-fast > > # Tauri 开发模式跳过 DuckDB -> pnpm tauri dev -- --no-default-features +> make dev-fast > ``` > > `--no-default-features` 仅影响本地开发，发布构建（`pnpm tauri build`）始终包含 DuckDB。 @@ -268,10 +269,18 @@ pnpm dev:tauri Web 版本： ```bash -pnpm dev:web # 前端 -pnpm dev:backend # 后端 +make dev-web # 前端 +make dev-backend # 后端 ``` +文档站： + +```bash +make docs +``` + +DBX 官网文档位于 `docs/` 目录。如果你想贡献官网内容或文档页面，请修改 `docs/` 下的文件，并运行 `make docs` 在本地预览文档站。 + JDBC Agent 驱动开发工程位于 `agents/` 目录： ```bash @@ -284,7 +293,7 @@ cd agents ### 构建 ```bash -pnpm tauri build +make package ``` 安装包输出在 `src-tauri/target/release/bundle/` 目录。 diff --git a/docs/content/docs/getting-started.cn.mdx b/docs/content/docs/getting-started.cn.mdx index 7c52a5344..7d80ccd91 100644 --- a/docs/content/docs/getting-started.cn.mdx +++ b/docs/content/docs/getting-started.cn.mdx @@ -183,6 +183,7 @@ description: 安装 DBX、创建第一个连接，并了解桌面版、Docker - [Node.js](https://nodejs.org/) >= 18 - [pnpm](https://pnpm.io/) +- Make - [Rust](https://www.rust-lang.org/tools/install) >= 1.77 ### 系统依赖 @@ -198,21 +199,22 @@ description: 安装 DBX、创建第一个连接，并了解桌面版、Docker ```bash git clone https://github.com/t8y2/dbx.git cd dbx -pnpm install -pnpm dev:tauri +make ``` +`make` 会在需要时安装根目录依赖，并启动本地 Tauri 桌面端开发环境。 + Web 版本： ```bash -pnpm dev:web -pnpm dev:backend +make dev-web +make dev-backend ``` ### 构建桌面安装包 ```bash -pnpm tauri build +make package ``` 桌面安装包会输出到 `src-tauri/target/release/bundle/`。 diff --git a/docs/content/docs/getting-started.mdx b/docs/content/docs/getting-started.mdx index b5bff7103..311b552bd 100644 --- a/docs/content/docs/getting-started.mdx +++ b/docs/content/docs/getting-started.mdx @@ -183,6 +183,7 @@ Use source mode when contributing or debugging DBX locally. - [Node.js](https://nodejs.org/) >= 18 - [pnpm](https://pnpm.io/) +- Make - [Rust](https://www.rust-lang.org/tools/install) >= 1.77 ### System Dependencies @@ -198,21 +199,22 @@ Use source mode when contributing or debugging DBX locally. ```bash git clone https://github.com/t8y2/dbx.git cd dbx -pnpm install -pnpm dev:tauri +make ``` +`make` installs root dependencies when needed and starts the local Tauri desktop development environment. + For the web version: ```bash -pnpm dev:web -pnpm dev:backend +make dev-web +make dev-backend ``` ### Build Desktop Packages ```bash -pnpm tauri build +make package ``` Desktop installers are written to `src-tauri/target/release/bundle/`. diff --git a/docs/pnpm-workspace.yaml b/docs/pnpm-workspace.yaml new file mode 100644 index 000000000..dbb26c827 --- /dev/null +++ b/docs/pnpm-workspace.yaml @@ -0,0 +1,3 @@ +allowBuilds: + esbuild: true + sharp: true