From 2ad6e85f3bf1649e74669a74b45eaca632376b7d Mon Sep 17 00:00:00 2001 From: Novus Nota <68142933+novusnota@users.noreply.github.com> Date: Tue, 14 Jan 2025 05:11:51 +0100 Subject: [PATCH 1/4] feat(docs): compilation report --- CHANGELOG.md | 1 + docs/astro.config.mjs | 5 +- docs/src/content/docs/book/compile.mdx | 104 ++++++++++++++++++++++ docs/src/content/docs/book/debug.mdx | 4 +- docs/src/content/docs/book/deploy.mdx | 3 - docs/src/content/docs/ref/core-common.mdx | 2 +- src/generator/writeReport.ts | 38 ++++---- 7 files changed, 132 insertions(+), 25 deletions(-) create mode 100644 docs/src/content/docs/book/compile.mdx diff --git a/CHANGELOG.md b/CHANGELOG.md index eaf53e5e6..2b14db9ef 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -71,6 +71,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Fixed links in Chinese translation: PR [#1206](https://github.com/tact-lang/tact/pull/1206) - Added a note on 255 being the maximum number of messages that can be sent during action phase: PR [#1237](https://github.com/tact-lang/tact/pull/1237) - Added onchain metadata creation for NFTs and Jettons to the cookbook: PR [#1236](https://github.com/tact-lang/tact/pull/1236) +- Added a compilation-related page with the description of the compilation report: PR [#1309](https://github.com/tact-lang/tact/pull/1309) ### Release contributors diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index fbc654998..8c8ff3779 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -180,10 +180,11 @@ export default defineConfig({ label: 'Going places', translations: { 'zh-CN': 'ε‰εΎ€ε„εœ°' }, attrs: { class: 'sidebar-separator' }, - link: 'book/deploy#', + link: 'book/compile#', }, - { slug: 'book/deploy' }, + { slug: 'book/compile' }, { slug: 'book/debug' }, + { slug: 'book/deploy' }, { slug: 'book/upgrades' }, { slug: 'book/import' }, { slug: 'book/config' }, diff --git a/docs/src/content/docs/book/compile.mdx b/docs/src/content/docs/book/compile.mdx new file mode 100644 index 000000000..90d0ad133 --- /dev/null +++ b/docs/src/content/docs/book/compile.mdx @@ -0,0 +1,104 @@ +--- +title: Compilation +description: "How to compile Tact smart contracts, as well as details on the build artifacts that are provided." +prev: + link: /book/message-mode + label: Message mode +--- + +import { Badge } from '@astrojs/starlight/components'; + +:::note + + This page is still being written as per [#1136](https://github.com/tact-lang/tact-docs/issues/1136). + +::: + +The Tact compiler can produce various outputs, ranging from the [BoC](/book/cells#cells-boc) of the compiled contract to various supplementary files, such as the [compilation report](#report) or the [contract package](/ref/evolution/otp-006), which is the JSON file with the `.pkg` extension that one can use to [verify the smart contract's origin](https://verifier.ton.org). + +With the proper [configuration settings](/book/config), you can customize the behavior of the compiler to skip the generation of some or all the [build artifacts](#artifacts), and even control the addition or exclusion of [getters for supported interfaces](/book/contracts#interfaces). + +Since the Tact compiler is a command-line program, some of the configuration settings can be set directly. When inside a folder with a Tact-based project, such as one created using the [Blueprint](https://github.com/ton-org/blueprint) or from the [tact-template](https://github.com/tact-lang/tact-template), refer to the `npx tact --help{:shell}` command for further instructions. + +## Build artifacts {#artifacts} + +A number of build artifacts can be produced per compilation of each contract. Some of the artifacts can be omitted using [configuration settings](/book/config). + +The location of the artifacts depends on the [`output`](/book/config#projects-output) field of the [`tact.config.json`](/book/config). In [Blueprint][bp]-based projects, `output` is not used and all generated files are always placed in `build/ProjectName/`. + +### Compilation report, `.md` {#report} + +Every markdown compilation report first features the name of the contract that it was prepared for and then the byte size of the contract compiled to [BoC](/book/cells#cells-boc). + +The following sub-headings describe the respective sections of the `.md` report. + +#### Structures {#structures} + +

+ +The first section introduces the present structures, i.e. some of the [composite types](/book/types#composite-types), [Structs and Messages](/book/structs-and-messages) that are declared or imported directly in the contract code, as well as those exposed from the Core standard library. + +Along with the number of structures present, each of the [Structs][struct] and [Messages][message] are described with their respective [TL-B schemas][tlb] and Tact signatures. + +For example: + +```md +Total structures: 10 + +### StateInit +TL-B: `_ code:^cell data:^cell = StateInit` +Signature: `StateInit{code:^cell,data:^cell}` + +### StdAddress +TL-B: `_ workchain:int8 address:uint256 = StdAddress` +Signature: `StdAddress{workchain:int8,address:uint256}` + +...etc. +``` + +#### Get methods {#getters} + +This section specifies the number of available get methods or [getter functions](/book/functions#getter-functions) and outlines them with their argument names, if any. + +For example: + +```md +Total get methods: 2 + +## lshift +Argument: x + +## gas +``` + +There, the `lshift(){:tact}` getter has a single argument `x`, whereas the `gas(){:tact}` getter has no arguments. + +#### Exit codes {#exit-codes} + +This section lists all default [exit codes](/book/exit-codes), as well as those generated from the error messages of the [`require(){:tact}`](/ref/core-debug#require), along with those messages for your convenience. + +For example: + +```md +* 2: Stack underflow +* 3: Stack overflow +...etc. +* 135: Code of a contract was not found +* 42933: Hey, I'm the error message of require() +``` + +There, the [exit codes](/book/exit-codes) in the range from $0$ to $255$ are those reserved by TON Blockchain or Tact compiler, while the exit code of $42933$ is produced by the respective call to the [`require(){:tact}`](/ref/core-debug#require) function. + +#### Trait inheritance diagram {#trait-diagram} + +This section shows a [Mermaid][mm] diagram of inherited [traits](/book/types#traits), including the [`BaseTrait{:tact}`](/ref/core-base). + +#### Contract inheritance diagram {#contract-diagram} + +This section shows a [Mermaid][mm] diagram of [contract](/book/contracts) dependencies, i.e. the [traits](/book/types#traits) that it depends upon. + +[struct]: /book/structs-and-messages#structs +[message]: /book/structs-and-messages#messages + +[tlb]: https://docs.ton.org/develop/data-formats/tl-b-language +[mm]: https://mermaid.js.org/ diff --git a/docs/src/content/docs/book/debug.mdx b/docs/src/content/docs/book/debug.mdx index 45ad2595c..77b28d521 100644 --- a/docs/src/content/docs/book/debug.mdx +++ b/docs/src/content/docs/book/debug.mdx @@ -1,6 +1,6 @@ --- -title: Debugging Tact contracts -description: "Various ways to reveal problems or bugs in Tact code" +title: Debugging and testing +description: "Various ways to reveal and prevent problems or bugs in Tact code" --- import { LinkCard, CardGrid, Steps, Tabs, TabItem } from '@astrojs/starlight/components'; diff --git a/docs/src/content/docs/book/deploy.mdx b/docs/src/content/docs/book/deploy.mdx index 92b5ba397..23c0573e6 100644 --- a/docs/src/content/docs/book/deploy.mdx +++ b/docs/src/content/docs/book/deploy.mdx @@ -1,9 +1,6 @@ --- title: Deployment description: "Common ways to deploy Tact contracts to testnet or mainnet of TON Blockchain" -prev: - link: /book/message-mode - label: Message mode --- Tact Deployer is a small library that integrates with [TON Verifier](https://verifier.ton.org) that allows you to deploy your contracts safely using your favorite wallet without needing to manage keys or deploy contracts manually. Tact Deployer also automatically verifies your contract's source code and you can be sure that your compiler is not compromised. diff --git a/docs/src/content/docs/ref/core-common.mdx b/docs/src/content/docs/ref/core-common.mdx index 5444ece78..e93ee2955 100644 --- a/docs/src/content/docs/ref/core-common.mdx +++ b/docs/src/content/docs/ref/core-common.mdx @@ -98,7 +98,7 @@ Field | Type | Description `bounced` | [`Bool{:tact}`][bool] | [Bounced](https://ton.org/docs/learn/overviews/addresses#bounceable-vs-non-bounceable-addresses) flag of the incoming message. `sender` | [`Address{:tact}`][p] | Internal address of the sender on the TON blockchain. `value` | [`Int{:tact}`][int] | Amount of [nanoToncoins](/book/integers#nanotoncoin) in a message. -`raw` | [`Slice{:tact}`][slice] | The remainder of the message as a [`Slice{:tact}`][slice]. It follows [internal message layout](https://docs.ton.org/develop/smart-contracts/messages#message-layout) of TON starting from the destination [`Address{:tact}`][p] (`dest:MsgAddressInt ` in [TL-B notation](https://docs.ton.org/develop/data-formats/tl-b-language)). +`raw` | [`Slice{:tact}`][slice] | The remainder of the message as a [`Slice{:tact}`][slice]. It follows [internal message layout](https://docs.ton.org/develop/smart-contracts/messages#message-layout) of TON starting from the destination [`Address{:tact}`][p] (`MsgAddressInt` in [TL-B notation](https://docs.ton.org/develop/data-formats/tl-b-language)). Usage example: diff --git a/src/generator/writeReport.ts b/src/generator/writeReport.ts index 62250f53d..c3ce4c959 100644 --- a/src/generator/writeReport.ts +++ b/src/generator/writeReport.ts @@ -9,41 +9,45 @@ export function writeReport(ctx: CompilerContext, pkg: PackageFileFormat) { const w = new Writer(); const abi = JSON.parse(pkg.abi) as ContractABI; w.write(` - # TACT Compilation Report + # Tact compilation report Contract: ${pkg.name} - BOC Size: ${Buffer.from(pkg.code, "base64").length} bytes + BoC Size: ${Buffer.from(pkg.code, "base64").length} bytes `); w.append(); - // Types - w.write(`# Types`); - w.write("Total Types: " + abi.types!.length); + // Structures + w.write(`## Structures (Structs and Messages)`); + w.write("Total structures: " + abi.types!.length); w.append(); for (const t of abi.types!) { const tt = getType( ctx, t.name.endsWith("$Data") ? t.name.slice(0, -5) : t.name, ); - w.write(`## ${t.name}`); - w.write(`TLB: \`${tt.tlb!}\``); + w.write(`### ${t.name}`); + w.write(`TL-B: \`${tt.tlb!}\``); w.write(`Signature: \`${tt.signature!}\``); w.append(); } // Get methods - w.write(`# Get Methods`); - w.write("Total Get Methods: " + abi.getters!.length); + w.write(`## Get methods`); + w.write("Total get methods: " + abi.getters!.length); w.append(); for (const t of abi.getters!) { w.write(`## ${t.name}`); - for (const arg of t.arguments!) { - w.write(`Argument: ${arg.name}`); + if (t.arguments!.length === 0) { + w.write(`This getter has no arguments`); + } else { + for (const arg of t.arguments!) { + w.write(`Argument: ${arg.name}`); + } } w.append(); } - // Error Codes - w.write(`# Error Codes`); + // Exit codes + w.write(`## Exit codes`); Object.entries(abi.errors!).forEach(([t, abiError]) => { w.write(`* ${t}: ${abiError.message}`); }); @@ -52,8 +56,8 @@ export function writeReport(ctx: CompilerContext, pkg: PackageFileFormat) { const t = getType(ctx, pkg.name); const writtenEdges: Set = new Set(); - // Trait Inheritance Diagram - w.write(`# Trait Inheritance Diagram`); + // Trait inheritance diagram + w.write(`## Trait inheritance diagram`); w.append(); w.write("```mermaid"); w.write("graph TD"); @@ -75,8 +79,8 @@ export function writeReport(ctx: CompilerContext, pkg: PackageFileFormat) { writtenEdges.clear(); - // Contract Dependency Diagram - w.write(`# Contract Dependency Diagram`); + // Contract dependency diagram + w.write(`## Contract dependency diagram`); w.append(); w.write("```mermaid"); w.write("graph TD"); From 33a2ea7a2046fdbbef62d3cb609067c6b5b4741f Mon Sep 17 00:00:00 2001 From: Novus Nota <68142933+novusnota@users.noreply.github.com> Date: Tue, 14 Jan 2025 06:02:30 +0100 Subject: [PATCH 2/4] fix: suggestions from the code review --- docs/src/content/docs/book/compile.mdx | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/src/content/docs/book/compile.mdx b/docs/src/content/docs/book/compile.mdx index 90d0ad133..fc8a290b0 100644 --- a/docs/src/content/docs/book/compile.mdx +++ b/docs/src/content/docs/book/compile.mdx @@ -10,7 +10,7 @@ import { Badge } from '@astrojs/starlight/components'; :::note - This page is still being written as per [#1136](https://github.com/tact-lang/tact-docs/issues/1136). + This page is still being written as per [#1136](https://github.com/tact-lang/tact/issues/1136). ::: @@ -56,6 +56,18 @@ Signature: `StdAddress{workchain:int8,address:uint256}` ...etc. ``` +[TL-B schema][tlb] of each [Message][message] contains its opcode, which is handy for looking up the auto-generated opcodes as well as confirming the [manually provided ones](/book/structs-and-messages#message-opcodes). For example: + +```md +## Deploy +TL-B: `deploy#946a98b6 queryId:uint64 = Deploy` +Signature: `Deploy{queryId:uint64}` + +## Seven +TL-B: `seven#00000007 = Seven` +Signature: `Seven{}` +``` + #### Get methods {#getters} This section specifies the number of available get methods or [getter functions](/book/functions#getter-functions) and outlines them with their argument names, if any. From 364e77985fa85b09fe8c80b7b06e1529a9ef6c10 Mon Sep 17 00:00:00 2001 From: Novus Nota <68142933+novusnota@users.noreply.github.com> Date: Tue, 14 Jan 2025 06:15:43 +0100 Subject: [PATCH 3/4] whoopsie --- docs/src/content/docs/book/compile.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/content/docs/book/compile.mdx b/docs/src/content/docs/book/compile.mdx index fc8a290b0..9e5725d8c 100644 --- a/docs/src/content/docs/book/compile.mdx +++ b/docs/src/content/docs/book/compile.mdx @@ -59,11 +59,11 @@ Signature: `StdAddress{workchain:int8,address:uint256}` [TL-B schema][tlb] of each [Message][message] contains its opcode, which is handy for looking up the auto-generated opcodes as well as confirming the [manually provided ones](/book/structs-and-messages#message-opcodes). For example: ```md -## Deploy +### Deploy TL-B: `deploy#946a98b6 queryId:uint64 = Deploy` Signature: `Deploy{queryId:uint64}` -## Seven +### Seven TL-B: `seven#00000007 = Seven` Signature: `Seven{}` ``` From dd98e94fa1033c52ef10efc05760c61af3d88d64 Mon Sep 17 00:00:00 2001 From: Novus Nota <68142933+novusnota@users.noreply.github.com> Date: Tue, 14 Jan 2025 06:32:46 +0100 Subject: [PATCH 4/4] not a Tact signature, strictly speaking --- docs/src/content/docs/book/compile.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/content/docs/book/compile.mdx b/docs/src/content/docs/book/compile.mdx index 9e5725d8c..829039bde 100644 --- a/docs/src/content/docs/book/compile.mdx +++ b/docs/src/content/docs/book/compile.mdx @@ -38,7 +38,7 @@ The following sub-headings describe the respective sections of the `.md` report. The first section introduces the present structures, i.e. some of the [composite types](/book/types#composite-types), [Structs and Messages](/book/structs-and-messages) that are declared or imported directly in the contract code, as well as those exposed from the Core standard library. -Along with the number of structures present, each of the [Structs][struct] and [Messages][message] are described with their respective [TL-B schemas][tlb] and Tact signatures. +Along with the number of structures present, each of the [Structs][struct] and [Messages][message] are described with their respective [TL-B schemas][tlb] and signatures. For example: