5 releases
0.1.4 | Apr 12, 2024 |
---|---|
0.1.3 | Apr 11, 2024 |
0.1.2 | Apr 10, 2024 |
0.1.1 | Apr 8, 2024 |
0.1.0 | Apr 8, 2024 |
#241 in Configuration
103 downloads per month
Used in 7 crates
11KB
darling-api
Note: darling-api is still pre-1.0, and breaking changes will occur. Consider very carefully if you actually want to implement an API that will certainly have breaking changes in the near future and require updates.
darling-api
is the library crate that allows custom implementations of darling. Darling is designed to specifically be extendible without changing darling itself, so that anyone can implement it for their package manager without having to contribute to darling itself. This API provides the necessary capabilities to implement darling.
Usage
This API can be implemented either by modifying a pre-existing template, or by creating a new crate from scratch. The template is recommended due to some quirks about naming, but you're free to start from scratch if you understand how to implement it correctly.
Implementing From Template
darling-template provides a starting point for implementing darling. To use it, first set the template up onto your local machine:
With version contol
Open the repository and click "Use this template > Create a new repository". This will set up a git repo that you can clone onto your local machine and begin development with git immediately.
Without version control
If you don't want to make a git repository for your project right now, you can just clone the template to get it onto your local machine.
Next steps
Next, rename the struct and implement the missing methods. Read the documentation for each method carefully to understand what it must do and not do. Do not rename the global PACKAGE_MANAGER
variable.
Edit your crate name in Cargo.toml
, and ensure it starts with darling-
, such as darling-npm
or darling-vscode
. Publish your crate when it's done!
That's it! once your crate is published, it can be used by anyone with darling, no updates required.
Manual Implementation
Alternatively, you can start from scratch and create a module without using a template. The process is as follows:
- Create a rust (library) project. It must start with
darling-
(technicallydarling_
is also allowed, but not the convention). For example,cargo new darling-example --lib
. Ensure that your name isn't taken on crates.io. - Add
darling-api
to your dependencies withcargo add darling-api
. - Create an empty struct that implements
darling::PackageManager
.- Ensure that the
get_name()
function returns a consistent value on all calls, and that it does not return "module".module
is a built-in reserved name used by darling to manage itself. Also, it should be unique to other darling modules, or else they will be incompatible. It is convention to make it the name of your crate, without thedarling-
prefix. For example, the `darling
- Ensure that the
- Declare a
pub static
variable of your struct with the namePACKAGE_MANAGER
that is accessible from your crate root. - Publish your crate on
crates.io
withcargo publish
Dependencies
~135KB