cjo Artifacts

This chapter introduces the cjo (Cangjie Object) artifacts generated during the Cangjie programming language compilation process and their related information.

What are cjo Artifacts

cjo (Cangjie Object) is a binary format AST (Abstract Syntax Tree) file generated by the Cangjie compiler, primarily serving a role similar to C language header files. cjo files contain interface information, type definitions, function declarations, and other metadata of packages, used for semantic checking and type checking during compilation. In addition to interface metadata, cjo files may also contain partial implementation content in certain special scenarios, such as inline functions, some expressions, and other code fragments that need to be expanded during compilation.

Functions of cjo Files

Interface Description

cjo files record public interface information of packages, including type definitions, function signatures, constant declarations, etc., similar to the role of header files in C language.

Compile-time Dependency Resolution

During compilation, the compiler obtains interface information of imported packages through cjo files for semantic checking and type checking, without needing to reparse source code.

Modular Support

cjo files enable decoupling between modules, allowing separation of package interfaces and implementations, supporting independent compilation and distribution.

Cross-package Dependency Management

Through cjo files, the compiler can effectively manage dependencies between packages, ensuring type safety and interface consistency.

Generation of cjo Files

Automatic Generation During Package Compilation

When compiling packages with cjc, corresponding cjo files are automatically generated:

$ cjc -p mypackage --output-type=staticlib

The compiler generates mypackage.cjo file and corresponding library files.

Specifying Output Directory

You can use the --output-dir option to specify the output directory for cjo files:

$ cjc -p mypackage --output-type=staticlib --output-dir ./build

cjo Files for Macro Packages

For macro packages, compilation generates cjo files with macro attributes:

$ cjc --compile-macro macro_define.cj --output-dir ./target

Usage of cjo Files

Working with --import-path

cjo files are primarily used with the --import-path option to specify search paths. Given the following directory structure:

.
├── libs
|   └── myModule
|       ├── log.cjo
|       └── libmyModule.a
└── main.cj

You can use cjo files with the following command:

$ cjc main.cj --import-path ./libs libmyModule.a

The compiler uses ./libs/myModule/log.cjo file for semantic checking and compilation of main.cj.

Usage in CJPM

In the cjpm.toml configuration file, you can configure cjo file dependencies through bin-dependencies:

[target.x86_64-unknown-linux-gnu.bin-dependencies]
path-option = ["./test/pro0", "./test/pro1"]

[target.x86_64-unknown-linux-gnu.bin-dependencies.package-option]
"pro0.xoo" = "./test/pro0/pro0.xoo.cjo"
"pro0.yoo" = "./test/pro0/pro0.yoo.cjo"

Dependency Scanning

You can use the --scan-dependency option to scan dependency relationships of cjo files:

$ cjc --scan-dependency mypackage.cjo

Characteristics of cjo Files

Binary AST Format

cjo files use binary format to store abstract syntax tree information, providing higher parsing efficiency compared to text format.

Complete Interface Information

cjo files contain complete package interface information, including type definitions, function signatures, visibility, and other metadata.

Compiler Version Compatibility

Since the LTS version, the Cangjie compiler promises backward compatibility, where subsequent compiler versions can correctly handle cjo files generated by previous versions. Before the LTS version, cjo files generated by different compiler versions may have compatibility issues.

Macro Information Support

For macro packages, cjo files carry macro attribute information, supporting compile-time macro expansion.

Usage Recommendations

Using CANGJIE_PATH Environment Variable

You can specify cjo file search paths by setting the CANGJIE_PATH environment variable, with --import-path option having higher priority.

Binary Library Distribution

Distribute cjo files along with corresponding library files (.a or .so) to provide binary dependencies for other modules.

Frequently Asked Questions

What if cjo files are out of sync with source files

Delete outdated cjo files and recompile the corresponding packages.

How to view dependency information of cjo files

Use cjc --scan-dependency mypackage.cjo command to view dependency relationships.

Why can't cjo files be found

Check if --import-path settings are correct and ensure cjo files are in the specified search paths.

Can cjo files be used across platforms

Currently, cjo files do not support cross-platform usage. It is recommended to regenerate the corresponding cjo files on the target platform. Future versions are planned to support cross-platform usage.

Related Options

The following compilation options are related to cjo file generation and usage:

• --import-path <value>: Specifies search paths for imported module AST files
• --output-dir <value>: Controls the save directory for cjo files
• -p, --package: Automatically generates corresponding cjo files when compiling packages
• --scan-dependency: Scans dependency relationships of cjo files
• --compile-macro: Compiles macro packages to generate cjo files with macro attributes

Notes

1. Search Paths: Ensure cjo file search paths are correctly set through --import-path or CANGJIE_PATH.

2. File Synchronization: cjo files must stay synchronized with corresponding library files; version mismatches may cause compilation errors.

3. Version Compatibility: Since the LTS version, the Cangjie compiler promises backward compatibility, where new versions can correctly handle cjo files generated by previous versions. Before LTS versions, it's recommended to regenerate cjo files after compiler upgrades.

4. Macro Package Handling: cjo files for macro packages need to be used with corresponding dynamic library files, maintaining consistent path settings.

5. Dependency Resolution: The compiler performs semantic checking through cjo files, ensuring imported package interface information is complete and accurate.