RFC: Replace `lib/bs` and `lib/ocaml` with a single flat `lib/rescript` directory (v13)

Đang mở
  • Có gì không ổn?
#9,151 0 bình luận 1 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
35/100
Loại issue
Tái cấu trúc
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
javascript, node.js, ocaml
Lĩnh vực
build-system, tooling

Hướng nghiên cứu

Start with the checklist and trace output paths through rewatch-ocaml, analysis (find_files, packages, cmt), reanalyze, and gentype (module_resolver); then review the shared rewatch suite, rewatch-ocaml tests, and analysis fixtures. The proposal is a v13 layout migration across compiler, runtime packaging, editor integrations, tests, and docs. Done means the listed consumers and tests use lib/rescript, migration support and cleanup are covered, and the migration note documents new paths.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

Every package's build output lives in two directories with historical names: lib/bs (from BuckleScript) and lib/ocaml (the old bsb install directory). Most files exist in both. This RFC proposes replacing them with a single flat lib/rescript directory in v13.

Today: almost everything exists twice

The build writes each artifact to lib/bs/<srcdir>/ (nested like the sources), then copies it byte for byte into lib/ocaml/ (flat). Most consumers read only one of the two copies:

Artifact lib/bs/<srcdir>/ copy read by lib/ocaml/ copy read by
.res / .resi (copy of the source) nobody nobody (only the stdlib's copies in @rescript/runtime are read, by analysis)
.ast / .iast bsc (compile input), the dependency scan both build systems (persistent state: freshness, previous dependencies, removed modules)
.cmi the editor (createInterface, file watcher) bsc, through -I ../ocaml and each dependency's lib/ocaml; both build systems (timestamp: "interface last changed")
.cmj nobody after the build (copy source) bsc (cross-module inlining; derives the package as pkg/lib/ocaml/X.cmj)
.cmt / .cmti analysis, reanalyze, gentype, the editor both build systems (only the .cmt timestamp: "last compiled"); the stdlib's copies are read by analysis
.mlmap (namespaces) bsc nobody (only compared by the build)
compiled JS the build's cleanup (proves it owns an output) (none)
.compiler.log, compiler-info.json, .sourcedirs.json, ___incremental/ the editor, analysis, reanalyze, the build systems (none)

So each source file exists three times on disk, and the build output takes about twice the space it needs. For tests/tests (661 modules) that's 32 MB in lib/bs and 29 MB in lib/ocaml. The editor sees lib/ocaml only through the -I paths from rescript compiler-args. lib/ocaml exists because bsc needs one flat include directory per package, and lib/bs is nested by source directory. It is also the only directory @rescript/runtime ships.

Proposal
lib/rescript/
  X.ast  X.iast              parse output and build state
  X.cmi  X.cmj               bsc input: -I lib/rescript for the package and each dependency
  X.cmt  X.cmti              editor, analysis, reanalyze, gentype
  Ns.cmi Ns.cmj Ns.mlmap     namespace map
  .compiler.log
  compiler-info.json
  .sourcedirs.json
  build.lock                 replaces lib/rescript.lock and lib/rewatch.lock
  incremental/               editor scratch space, replaces lib/bs/___incremental
  • Flat: one directory per package, keyed by the compiler's file name for the module (X or X-Ns), as lib/ocaml is today. Module names are already unique within a package.
  • One copy of everything: no source copies and no JS mirror. Output ownership for cleanup comes from the build state instead.
  • Freshness stays timestamp-based: the .cmt marks "last compiled" and the .cmi marks "interface last changed". A .cmi is written to a temporary name and renamed into place only on success, and only when it changed. That keeps early cutoff, and dependents never see a half-written interface.
  • bsc barely changes: -I ../ocaml becomes -I lib/rescript. The .cmj package-path derivation keeps working, because pkg/lib/rescript/X.cmj has the same depth as pkg/lib/ocaml/X.cmj.
  • @rescript/runtime ships lib/rescript, and analysis reads the stdlib from there.
  • rescript clean removes lib/bs and lib/ocaml left over from earlier versions.
Checklist
  • rewatch-ocaml: output paths, publishing, freshness/state, the watcher's ignore list, compiler-args, clean
  • Remove the Rust rewatch first, so only one build system changes
  • analysis (find_files, packages, cmt): look up a module's files directly in lib/rescript instead of going through source directories
  • reanalyze (the .sourcedirs.json scan plan) and gentype (module_resolver): read <pkg>/lib/rescript
  • @rescript/runtime packaging (artifacts.json, .npmignore)
  • Tests: the shared rewatch suite, rewatch-ocaml's tests, and analysis fixtures that hard-code lib/bs/lib/ocaml
  • Docs, templates, and the migration note in the CHANGELOG
  • rescript-vscode and @rescript/language-server: choose the layout by compiler version (compiler-info.json, .compiler.log, watchers, incremental/, createInterface, incremental type-checking)
Migration
  • This is a breaking change for v13.
  • The editor extension supports both layouts, choosing by compiler version, so the build writes nothing to lib/bs for older editors.
  • Third-party tools that read lib/bs/.compiler.log or lib/ocaml directly, such as bundler plugins, need updating; the CHANGELOG lists the new paths.
Ngôn ngữ chính
OCaml
Star
7.5k
Fork
484
Merge trung bình
17 giờ 2 phút
Pull request đã merge (30 ngày)
249

Chuẩn bị môi trường

Mở trong Codespaces

Khởi chạy dev container của dự án ngay trên trình duyệt, bằng tài khoản GitHub của bạn.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của rescript-lang/rescript

Tất cả issue của rescript-lang/rescript

Issue tương tự

Thêm issue về Build System

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.