Soplang Package Reference Repository

This repository serves as a reference for developers to understand the structure and requirements of a valid Soplang package. It is not a template, but a guide that developers can follow when using the Soplang CLI to generate their package structure.

---

📌 Soplang Package Structure

A valid Soplang package must follow this structure:

/soplang-package-reference
├── src/              # Source code directory (Recommended but not required)
│   ├── main.so       # Main entry file (Defined in sop.toml)
│
├── sop.toml          # Package metadata file (Required)
├── LICENSE           # License file (Required)
├── README.md         # Documentation (Required)
├── .gitignore        # Prevents unnecessary files from being tracked (Required)

---

✅ Required Files & Directories

These files are mandatory for every Soplang package.

1️⃣ sop.toml (Required)

The metadata file that defines:

• Package identity (name, version, description, license).
• Dependencies required for the package to work.
• Entry point file (which file executes when the package is imported).
• Package classification (stability status, keywords, categories).

📜 Example sop.toml

[package]
name = "hello-world"
version = "1.0.0"
status = "stable"
description = "A simple Soplang package that prints 'Hello, Soplang!'"
license = "MIT"
author = "your-username"
repository = "https://github.com/your-username/hello-world"
homepage = "https://yourwebsite.com"
entry = "src/main.so"
keywords = ["soplang", "hello", "example"]
categories = ["utilities", "examples"]

[dependencies]
another-package = "^1.2.0"
some-library = ">=2.0.0, <3.0.0"

Explanation of sop.toml Fields

• [package] Section

  • name → A unique package name.
  • version → Uses Semantic Versioning (major.minor.patch).
  • status → Stability classification (stable, beta, alpha, etc.).
  • description → Short summary of what the package does.
  • license → Defines the legal terms (e.g., MIT, GPL).
  • author → The creator of the package.
  • repository → Link to the source code repository (GitHub, GitLab, etc.).
  • homepage → The website or documentation link.
  • entry → Defines which file is executed first (default: src/main.so).
  • keywords → Helps with package searchability in Soplang Hub.
  • categories → Classifies the package (e.g., "utilities", "examples").

• [dependencies] Section

  • Lists other Soplang packages required to run this package.
  • Uses version constraints (^1.2.0, >=2.0.0, <3.0.0).
  • These dependencies are automatically downloaded when the package is installed.

---

✅ Other Required Files

These files must be included to ensure a complete and usable package.

1️⃣ README.md (Required)

A documentation file explaining the package’s functionality, usage, and other details.

2️⃣ LICENSE (Required)

Defines the legal terms of usage for the package.

3️⃣ .gitignore (Required)

This file prevents unnecessary files from being committed to version control.

📜 Example .gitignore

# Ignore build artifacts
/dist

# Ignore editor and system files
.vscode/
.idea/
*.swp
.DS_Store
Thumbs.db

✅ Why .gitignore is required?

• Keeps repositories clean.
• Prevents editor settings and cache files from being committed.
• Avoids unnecessary binary files from bloating the repository.

---

🎯 Important Notes

• ✅ This is a reference repository, not a template.
• ✅ Developers should use the Soplang CLI to generate their package structure.
• ✅ This repository explains how a package should be structured.
• ✅ Developers can follow this reference to manually verify or adjust their package.

---

This reference helps developers understand the structure of Soplang packages and ensures their package meets Soplang Hub requirements. 🚀