From 68e03b1e1cf529dda669160649e3985e1298c180 Mon Sep 17 00:00:00 2001
From: zihang <yezihang@idea.edu.cn>
Date: Mon, 16 Dec 2024 14:35:56 +0800
Subject: [PATCH] doc: introduce package and modules

---
 next/language/packages.md                     | 24 +++++++++++++++++++
 .../language/src/packages/pkgA/moon.pkg.json  |  1 +
 .../language/src/packages/pkgA/top.mbt        |  3 +++
 .../language/src/packages/pkgB/moon.pkg.json  |  5 ++++
 .../language/src/packages/pkgB/top.mbt        |  3 +++
 5 files changed, 36 insertions(+)
 create mode 100644 next/sources/language/src/packages/pkgA/moon.pkg.json
 create mode 100644 next/sources/language/src/packages/pkgA/top.mbt
 create mode 100644 next/sources/language/src/packages/pkgB/moon.pkg.json
 create mode 100644 next/sources/language/src/packages/pkgB/top.mbt

diff --git a/next/language/packages.md b/next/language/packages.md
index d4ae6faf..c38850c0 100644
--- a/next/language/packages.md
+++ b/next/language/packages.md
@@ -1,5 +1,29 @@
 # Managing Projects with Packages
 
+When developing projects at large scale, the project usually needs to be divided into smaller modular unit that depends on each other. 
+More often, it involves using other people's work: most noticeably is the [core](https://github.com/moonbitlang/core), the standard library of MoonBit.
+
+## Packages and modules
+
+In MoonBit, the most important unit for code organization is a package, which consists of a number of source code files and a single `moon.pkg.json` configuration file.
+A package can either be a `main` package, consisting a `main` function, or a package that serves as a library. 
+
+A project, corresponding to a module, consists of multiple packages and a single `moon.mod.json` configuration file.
+
+When using things from another package, the dependency between modules should first be declared inside the `moon.mod.json`.
+The dependency between packages should then be declared inside the `moon.pkg.json`.
+Then it is possible to use `@pkg` to access the imported entities, where `pkg` is the last part of the imported package's path or the declared alias in `moon.pkg.json`:
+
+```{literalinclude} /sources/language/src/packages/pkgB/moon.pkg.json
+:language: json
+:caption: pkgB/moon.pkg.json
+```
+
+```{literalinclude} /sources/language/src/packages/pkgB/top.mbt
+:language: moonbit
+:caption: pkgB/top.mbt
+```
+
 ## Access Control
 
 By default, all function definitions and variable bindings are _invisible_ to other packages.
diff --git a/next/sources/language/src/packages/pkgA/moon.pkg.json b/next/sources/language/src/packages/pkgA/moon.pkg.json
new file mode 100644
index 00000000..9e26dfee
--- /dev/null
+++ b/next/sources/language/src/packages/pkgA/moon.pkg.json
@@ -0,0 +1 @@
+{}
\ No newline at end of file
diff --git a/next/sources/language/src/packages/pkgA/top.mbt b/next/sources/language/src/packages/pkgA/top.mbt
new file mode 100644
index 00000000..5c854fc4
--- /dev/null
+++ b/next/sources/language/src/packages/pkgA/top.mbt
@@ -0,0 +1,3 @@
+pub fn incr(x : Int) -> Int {
+  x + 1
+}
\ No newline at end of file
diff --git a/next/sources/language/src/packages/pkgB/moon.pkg.json b/next/sources/language/src/packages/pkgB/moon.pkg.json
new file mode 100644
index 00000000..1d39684f
--- /dev/null
+++ b/next/sources/language/src/packages/pkgB/moon.pkg.json
@@ -0,0 +1,5 @@
+{
+    "import": [
+        "moonbit-community/language/packages/pkgA"
+    ]
+}
\ No newline at end of file
diff --git a/next/sources/language/src/packages/pkgB/top.mbt b/next/sources/language/src/packages/pkgB/top.mbt
new file mode 100644
index 00000000..c1e62a52
--- /dev/null
+++ b/next/sources/language/src/packages/pkgB/top.mbt
@@ -0,0 +1,3 @@
+pub fn add1(x : Int) -> Int {
+  @pkgA.incr(x)
+}
\ No newline at end of file