LeonOS/data/computercraft/lua/rom/help/create_package.hlp

=== How To Create A Package ===

This guide explains how to create your own packages for LeonOS using the `pkg` command.

== Introduction ==

Packages are a way to distribute and reuse code in LeonOS. A package typically contains:
- A metadata file (package.json)
- One or more Lua files with your code
- Optional resources (images, configuration files, etc.)

== Creating a Package ==

To create a new package, use the `pkg init` command:

>>color yellow
pkg init <package_name>
>>color white

Replace `<package_name>` with a unique name for your package.

== Package Structure ==

After running `pkg init`, the following structure will be created in the `/packages/` directory:

/packages/
  <package_name>/
    1.0.0/
      package.json  - Package metadata
      <package_name>.lua - Main package file

== package.json Format ==

The package.json file contains metadata about your package. Here's an example:

>>color yellow
{
  "name": "<package_name>",
  "version": "1.0.0",
  "author": "Your Name",
  "description": "A brief description of your package",
  "main": "<package_name>.lua",
  "dependencies": {},
  "exports": {
    "function1": "function1",
    "function2": "function2"
  }
}
>>color white

- **name**: The name of your package (must match the directory name)
- **version**: The package version (semantic versioning recommended)
- **author**: Your name or username
- **description**: A short description of what the package does
- **type**: The type of your package ("app" for applications, "api" for libraries)
- **main**: The main Lua file to load
- **dependencies**: Other packages your package depends on
- **exports**: Functions or variables to export for other programs to use

== Package Type Field ==

The `type` field in package.json determines where your package files will be installed:

- **app**: Files will be installed in the `/app` directory (default behavior)
- **api**: Files will be installed in the `/leonos/apis` directory

Example of a package.json with type field:

>>color yellow
{
  "name": "example-api",
  "version": "1.0.0",
  "author": "Your Name",
  "description": "An example API package",
  "type": "api",
  "main": "example-api.lua",
  "dependencies": {},
  "exports": {}
}
>>color white

== Writing Package Code ==

Edit the `<package_name>.lua` file to add your code. Here's a simple example:

>>color yellow
-- <package_name>.lua

local mypackage = {}

function mypackage.function1(param)
  return "Hello, " .. param .. "!"
end

function mypackage.function2()
  return "This is function2"
end

return mypackage
>>color white

== Testing Your Package ==

To test your package before publishing, you can use it in a Lua program:

>>color yellow
-- test_package.lua

local mypackage = require("<package_name>")
print(mypackage.function1("world"))
>>color white

Run the test program:

>>color yellow
lua test_package.lua
>>color white

== Installing Your Package ==

Once your package is ready, you can install it locally:

>>color yellow
pkg install --local /packages/<package_name>/1.0.0/
>>color white

== Publishing Your Package ==

To share your package with others, you need to publish it to a package repository. This typically involves:

1. Creating an account on the repository
2. Uploading your package files
3. Registering your package

For more information on publishing, see the documentation for your chosen repository.

== Best Practices ==

- Use semantic versioning (major.minor.patch)
- Keep your package focused on a single purpose
- Document your functions and their parameters
- Test your package thoroughly
- Update the version number when you make changes

== Example Walkthrough ==

Let's create a simple package called "greeting":

1. Create the package:
>>color yellow
   pkg init greeting
>>color white

2. Edit package.json:
>>color yellow
   {
     "name": "greeting",
     "version": "1.0.0",
     "author": "Your Name",
     "description": "A simple greeting package",
     "main": "greeting.lua",
     "dependencies": {},
     "exports": {
       "sayHello": "sayHello"
     }
   }
>>color white

3. Edit greeting.lua:
>>color yellow
   -- greeting.lua

   local greeting = {}

   function greeting.sayHello(name)
     return "Hello, " .. name .. "! Welcome to LeonOS!"
   end

   return greeting
>>color white

4. Test the package:
>>color yellow
   -- test_greeting.lua
   local greeting = require("greeting")
   print(greeting.sayHello("User"))
>>color white

   Run with: lua test_greeting.lua

5. Install the package:
>>color yellow
   pkg install --local /packages/greeting/1.0.0/
>>color white

Now your package is ready to use in other programs!

For more information, run `pkg help` or check other help files in the /rom/help directory.