UCPeM is used to import packages into projects. A package is defined in using a port which is a special type of package, that exports resources. In a project these resources can be imported into resource links, which are folder junctions to the cloned repositories of ports.
To create a project run:
ucpem init
If you have a .gitignore file, it will be updated.
A project contains an ucpem.js or ucpem.ts file, defining resources and their dependencies.
Port is a repository path (for git clone). Resource names should be [a-zA-Z0-9_]+ and cannot contain whitespace.
Port must be a git clone URL. All cloned repos will be placed into a ucpem_ports folder in the root of the project. Don't worry about source control, a .gitignore file will be generated automatically.
To define a resource write:
const { project } = require("ucpem")
project.res("resource")To define a port and dependency write:
const { project, git, github } = require("ucpem")
const port = git("https://github.com/bt7s7k7/UCPeM")
// OR
const port = github("bt7s7k7/UCPeM")
project.res("resource",
port.res("dependency")
)Resources can have a preparation script. It's run when the port is cloned, updated or manually using ucpem prepare.
const { project, prepare } = require("ucpem")
project.res("resource",
prepare(async () => {
// ...
})
)Scripts have access to context information in the constants object.
const { project, prepare, constants } = require("ucpem")
project.res("resource",
prepare(async () => {
/** Path of the resource the callback is executed for */
constants.resourcePath
/** Path to this project */
constants.projectPath
/** Path to the install path, eq. to project path if not port */
constants.installPath
/** Is this project being installed as a port */
constants.isPort
/** Name of this project */
constants.projectName
/** Name of the project this port is being installed into */
constants.installName
})
)There are utility function you can use in prepare scripts:
const { project, prepare, link, join, run } = require("ucpem")
project.res("resource",
prepare(async () => {
/** Creates a symlink / junction, relative to resource */
link(link: string, target: string): void
/** Joins paths together */
join(...paths: string[]): string
/** Runs a command, cwd is resource path */
run(command: string): Promise<void>
})
)If your resources files are offset from the config folder (i.e. in a src folder) you can prefix the project path:
const { project, prepare } = require("ucpem")
const srcFolder = project.prefix("./src")
srcFolder.res("resource")You can also specify a unique path for a resource:
const { project, path } = require("ucpem")
project.res("resourceName",
path("./path/to/resource/resourceName")
)Sometimes you just want to import a resource to use during development, like testing util scripts:
const { project, git } = require("ucpem")
const port = git("../port")
project.prefix("test").use(port.res("testUtil"))During project development it is often beneficial to develop a dependency along with a project. To synchronize an imported port with it's source you can use local linking.
To publish a port for local linking run:
ucpem sync
This will create a symlink in a global ucpem folder, from which the port can be linked into a project:
ucpem sync with <port name>
You can use all as port name to made all installed ports synced if their ports are published for local linking.
The global folder is ~/.ucpem by default but it can be modified with the UCPEM_LOCAL_PORTS environmental variable.
By default during ucpem install, local ports are used before cloning a remote copy, to install remote ports only run ucpem install remote. You can also useucpem install local to only install local ports and error if any are missing.
Local linking requires node version ^12.10.0
To avoid issues caused by breaking changes in dependencies, you can use a lockfile to record commit hashes of all installed ports. If any dependencies evolve to cause errors with your application, UCPeM can then automatically checkout older commits.
Use ucpem lock update to record current dependencies and ucpem lock check to check for mismatches. If mismatches occur use ucpem lock apply to revert to last working version.
To keep your lockfile up-to-date, you can use a pre-commit hook. An example hook is reproduced below. It will prevent commits unless the lockfile is up-to-date. Save it as .git/hooks/pre-commit to enable this functionality.
#!/bin/zsh
# Skip this check if we are rebasing, it is likely we already checked those commits
if [[ "${GIT_REFLOG_ACTION}" =~ "rebase".*"reword" ]]; then
exit 0
fi
# Remove PREFIX otherwise nvm would complain
unset PREFIX
source ~/.zshrc
ucpem lock check- Install from source
git clone https://github.com/bt7s7k7/UCPeM.git
npm install
npm run build
npm link
- Install from npm
npm install ucpem
yarn add ucpem
Usage:
ucpem <operation>
Commands:
info - Displays information about the current project
info json - Displays all project resources in machine readable JSON format
info brief - Displays all project resources
install - Installs all missing ports
install remote - Install all missing ports without using local ports
install local - Install all missing ports without using local ports
prepare - Runs prepare scripts for all resources
update all - Updates all installed ports, including local linked
update check - For every installed port, checks git status to detect any changes
update - Updates all installed ports
link resolve - Changes links into real folders
link clean - Deletes all created links
link unresolve - Reverts changes made by `link resolve`
link - Links dependencies to resources
init - Creates a ucpem project
sync - Publishes this project for local linking
unsync - Removes this project from local linking
sync with - Syncs with a port that was published for local linking :: Arguments: <name>
unsync with - Removes a local linked port that was synced with :: Arguments: <name>
run - Runs a run script :: Arguments: <name> (...)
add to bin - Copies self to "node_modules/.bin" so it can be used with yarn, use thins when doing a curl install, only use with single file builds
alias - Create shorthand alias for a command :: Arguments: <name> <command...>
unalias - Remove alias :: Arguments: <name>
paths - Prints all system paths used by SMWA
lock update - Updates lock file to match installed ports
lock check - Checks lock file for mismatches with installed ports
lock apply - Applies lockfile refs to installed ports
Run ucpem without arguments to view help.