diff --git a/docs/shard.yml.adoc b/docs/shard.yml.adoc index f49b83dd..089c97f8 100644 --- a/docs/shard.yml.adoc +++ b/docs/shard.yml.adoc @@ -4,28 +4,28 @@ :man manual: File Formats :man source: shards {shards_version} -== NAME -shard.yml - metadata for projects managed by shards(1) +== Name +shard.yml - metadata for projects managed by *shards*(1) -== DESCRIPTION +== Description -The file _shard.yml_ is a YAML file with metadata about a project managed by shards, known as a *shard*. It must contain at least _name_ and _version_ attributes plus optional additional attributes. +The file *shard.yml* is a YAML file with metadata about a project managed by shards, known as a *shard*. It must contain at least _name_ and _version_ attributes plus optional additional attributes. -Both libraries and applications will benefit from `shard.yml`. +Both libraries and applications will benefit from *shard.yml*. The metadata for libraries are expected to have more information (e.g., list of authors, description, license) than applications that may only have a name, version and dependencies. -== FORMAT +== Format -The file must be named _shard.yml_ and be a valid YAML file with UTF-8 encoding. +The file must be named *shard.yml* and be a valid YAML file with UTF-8 encoding. It must not contain duplicate attributes in any mapping. It should use an indent of 2 spaces. It should not use advanced YAML features, only simple mappings, sequences and strings (Failsafe Schema). -== REQUIRED ATTRIBUTES +== Required Attributes *name*:: The name of the project (string, required). + @@ -33,7 +33,7 @@ strings (Failsafe Schema). - It must be unique. - It must be 50 characters or less. - It should be lowercase (a-z). -- It should not contain _crystal_. +- It should not contain *crystal*. - It may contain digits (0-9) but not start with one. - It may contain underscores or dashes but not start/end with one. - It must not have consecutive underscores or dashes. @@ -56,13 +56,13 @@ While Shards doesn't enforce it, following a rational versioning scheme like http://semver.org/[Semantic Versioning] or http://calver.org/[Calendar Versioning] is highly recommended. -== OPTIONAL ATTRIBUTES +== Optional Attributes *authors*:: A list of authors, along with their contact email (optional) (sequence of string). + -- - Each author must have a name. -- Each author may have an email address, within angle bracket (_<_ and _>_) +- Each author may have an email address, within angle bracket (*<* and *>*) chars. -- + @@ -82,14 +82,14 @@ usually express a lower and upper-bound constraints (string, recommended) When resolving dependencies, this information is not used. After dependecies have been determined shards checks all of them are expected to work with the current crystal version. If not, a warning appears for the offending -dependencies. The resolved versions are installed and can be used at your +dependencies. The resolved versions are installed and can be used at your own risk. + -The valid values are mostly the same as for _dependencies.version_: +The valid values are mostly the same as for *dependencies.version*: + -- -* A version number prefixed by an operator: _<_, _\<=_, _>_, _>=_ or _~>_. -* Just _"*"_ if any version will do (this is the default if unspecified). +* A version number prefixed by an operator: *<*, *\<=*, *>*, *>=* or *~>*. +* Just *"*"* if any version will do (this is the default if unspecified). * Multiple requirements can be separated by commas. -- There is a special legacy behavior (its use is discouraged) when just a version @@ -153,11 +153,11 @@ The URL to a website providing the project's documentation for online browsing ( A list of executables to be installed (sequence). + The executables can be of any type or language (e.g., shell, binary, ruby), must -exist in the _bin_ folder of the Shard, and have the executable bit set (on +exist in the *bin/* folder of the Shard, and have the executable bit set (on POSIX platforms). When installed as a dependency for another project the -executables will be copied to the _bin_ folder of that project. +executables will be copied to the *bin/* folder of that project. + -Executables are always installed last, after the _postinstall_ script is run, so +Executables are always installed last, after the *postinstall* script is run, so libraries can build the executables when they are installed by Shards. + *Example:* @@ -183,15 +183,15 @@ libraries that are only referenced by dependencies. It must include all librarie it directly links to, regardless of a dependency doing it too. + It should map from the soname without any extension, path or version, -for example _libsqlite3_ for _/usr/lib/libsqlite3.so.0.8.6_, to a version +for example *libsqlite3* for */usr/lib/libsqlite3.so.0.8.6*, to a version constraint. + The version constraint has the following format: + -- - It may be a version number. -- It may be _"*"_ if any version will do. -- The version number may be prefixed by an operator: _<_, _\<=_, _>_, _>=_ or _~>_. +- It may be *"*"* if any version will do. +- The version number may be prefixed by an operator: *<*, *\<=*, *>*, *>=* or *~>*. -- + [source,yaml] @@ -210,7 +210,7 @@ libraries: The URL of the project's canonical repository (string, recommended). + The URL should be compatible with typical VCS tools without modifications. -_http_/_https_ is preferred over VCS schemes like _git_. +*http*/*https* is preferred over VCS schemes like *git*. It is recommended that this URL is publicly available. + Copies of a shard (such as mirrors, development forks etc.) should point to the same @@ -224,18 +224,18 @@ repository: "https://github.com/crystal-lang/shards" ---- *scripts*:: - Script hooks to run. Only _postinstall_ is supported. + Script hooks to run. Only *postinstall* is supported. + Shards may run scripts automatically after certain actions. The scripts themselves are mere shell commands. *postinstall*::: -The _postinstall_ hook of a dependency will be run whenever that dependency is +The *postinstall* hook of a dependency will be run whenever that dependency is installed or upgraded in a project that requires it. This may be used to compile a C library, to build tools to help working on the project, or anything else. + The script will be run from the dependency's installation directory, for example -_lib/foo_ for a Shard named _foo_. +*lib/foo* for a Shard named *foo*. + *Example:* + @@ -250,7 +250,7 @@ A list of targets to build (mapping). + Each target begins with the name of the target as a key (string), then a list of attributes (mapping). The target name is the built binary name, created in the -_bin_ folder of the project. +*bin/* folder of the project. + *Example:* + @@ -263,22 +263,22 @@ targets: main: src/worker.cr ---- + -The above example will build _bin/server_ from _src/server/cli.cr_ and -_bin/worker_ from _src/worker.cr_. +The above example will build *bin/server* from *src/server/cli.cr* and +*bin/worker* from *src/worker.cr*. *main*::: A path to the source file to compile (string). -== DEPENDENCY ATTRIBUTES +== Dependency Attributes Each dependency needs at least one attribute that defines the resolver for this -dependency. Those can be _path_, _git_, _github_, _gitlab_, _bitbucket_. +dependency. Those can be *path*, *git*, *github*, *gitlab*, *bitbucket*. *path*:: A local path (string). + The library will be installed as a symlink to the local path. -The _version_ attribute isn't required but will be used if present to validate +The *version* attribute isn't required but will be used if present to validate the dependency. *git*:: @@ -288,56 +288,56 @@ The URL may be [any protocol](https://git-scm.com/docs/git-clone#_git_urls) supported by Git, which includes SSH, GIT and HTTPS. + The Git repository will be cloned, the list of versions (and associated -_shard.yml_) will be extracted from Git tags (e.g., _v1.2.3_). +*shard.yml*) will be extracted from Git tags (e.g., _v1.2.3_). + -One of the other attributes (_version_, _tag_, _branch_ or _commit_) is +One of the other attributes (*version*, *tag*, *branch* or *commit*) is required. When missing, Shards will install the HEAD refs. + -*Example:* _git: git://git.example.org/crystal-library.git_ +Example: *git: git://git.example.org/crystal-library.git* *github*:: -GitHub repository URL as _user/repo_ (string) +GitHub repository URL as *user/repo* (string) + -Extends the _git_ resolver, and acts exactly like it. +Extends the *git* resolver, and acts exactly like it. + -*Example:* _github: ysbaddaden/minitest.cr_ +Example: *github: ysbaddaden/minitest.cr* *gitlab*:: -GitLab repository URL as _user/repo_ (string). +GitLab repository URL as *user/repo* (string). + -Extends the _git_ resolver, and acts exactly like it. +Extends the *git* resolver, and acts exactly like it. + -Only matches dependencies hosted on _gitlab.com_. For personal GitLab -installations, you must use the generic _git_ resolver. +Only matches dependencies hosted on *gitlab.com*. For personal GitLab +installations, you must use the generic *git* resolver. + -*Example:* _gitlab: thelonlyghost/minitest.cr_ +Example: *gitlab: thelonlyghost/minitest.cr* *bitbucket*:: -Bitbucket repository URL as _user/repo_ (string). +Bitbucket repository URL as *user/repo* (string). + -Extends the _git_ resolver, and acts exactly like it. +Extends the *git* resolver, and acts exactly like it. + -*Example:* _bitbucket: tom/library_ +*Example:* *bitbucket: tom/library* *version*:: A version requirement (string). + -- - It may be an explicit version number. -- It may be _"*"_ wildcard if any version will do (this is the default). +- It may be *"*"* wildcard if any version will do (this is the default). Shards will then install the latest tagged version (or HEAD if no tagged version available). -- The version number may be prefixed by an operator: _<_, _\<=_, _>_, _>=_ or _~>_. +- The version number may be prefixed by an operator: *<*, *\<=*, *>*, *>=* or *~>*. - Multiple requirements can be separated by commas. -- + Examples: _1.2.3_, _>= 1.0.0_, _>= 1.0.0, < 2.0_ or _~> 2.0_. + -Most of the version operators, like _>= 1.0.0_, are self-explanatory, but -the _~>_ operator has a special meaning, best shown by example: +Most of the version operators, like *>= 1.0.0*, are self-explanatory, but +the *~>* operator has a special meaning, best shown by example: -- -- _~> 2.0.3_ is identical to _>= 2.0.3 and < 2.1_; -- _~> 2.1_ is identical to _>= 2.1 and < 3.0_. +- *~> 2.0.3* is identical to *>= 2.0.3 and < 2.1*; +- *~> 2.1* is identical to *>= 2.1 and < 3.0*. -- *branch*:: @@ -351,7 +351,7 @@ the _~>_ operator has a special meaning, best shown by example: == Example: -Here is an example _shard.yml_ for a library named _shards_ at version _1.2.3_ +Here is an example *shard.yml* for a library named *shards* at version *1.2.3* with some dependencies: [source,yaml] @@ -388,8 +388,8 @@ targets: main: src/shards.cr ---- -== AUTHOR +== Author Written by Julien Portalier and the Crystal project. -== SEE ALSO +== See Also *shards*(1) diff --git a/docs/shards.adoc b/docs/shards.adoc index 2660ed61..97d77fd6 100644 --- a/docs/shards.adoc +++ b/docs/shards.adoc @@ -4,26 +4,26 @@ :man manual: Shards Manual :man source: shards {shards_version} -== NAME +== Name shards - dependency manager for the Crystal Language -== SYNOPSIS -*shards* [__...] [__] [__...] +== Synopsis +*shards [...] [] [...]* -== DESCRIPTION +== Description Manages dependencies for Crystal projects and libraries with reproducible installs across computers and systems. -== USAGE -_shards_ requires the presence of a _shard.yml_ file in the project +== Usage +_shards_ requires the presence of a *shard.yml* file in the project folder (working directory). This file describes the project and lists dependencies that are required to build it. See *shard.yml*(5) for more -information on its format. A default file can be created by running _shards init_. +information on its format. A default file can be created by running *shards init*. -Running _shards install_ resolves and installs the +Running *shards install* resolves and installs the specified dependencies. The installed versions are written into a *shard.lock* file for using the exact same dependency versions when -running _shards install_ again. +running *shards install* again. If your shard builds an application, both *shard.yml* and *shard.lock* should be checked into version control to provide reproducible @@ -32,148 +32,148 @@ If it is only a library for other shards to depend on, *shard.lock* should _not_ be checked in, only *shard.yml*. It’s good advice to add it to *.gitignore*. -== COMMANDS +== Commands If no _command_ is given, *install* command will be run by default. -To see the available options for a particular command, use _--help_ after the command. +To see the available options for a particular command, use *--help* after the command. -*build* [__] [__...]:: -Builds the specified __ in *bin* path. If no targets are specified, +*build [] [...]*:: +Builds the specified *targets* in *bin/* path. If no targets are specified, all are built. This command ensures all dependencies are installed, so it is not necessary to run *shards install* before. + -All __ following the command are delegated to *crystal build*. +All *build_options* following the command are delegated to *crystal build*. *check*:: Verifies that all dependencies are installed and requirements are satisfied. + Exit status: + -[horizontal] -*0*::: Dependencies are satisfied. -*1*::: Dependencies are not satisfied. +*0*: Dependencies are satisfied. ++ +*1*: Dependencies are not satisfied. *init*:: -Initializes a default _shard.yml_ in the current folder. +Initializes a default *shard.yml* in the current folder. -*install* [--frozen] [--without-development] [--production] [--skip-postinstall]:: -Resolves and installs dependencies into the _lib_ folder. If not already -present, generates a _shard.lock_ file from resolved dependencies, locking +*install [--frozen] [--without-development] [--production] [--skip-postinstall]*:: +Resolves and installs dependencies into the *lib/* folder. If not already +present, generates a *shard.lock* file from resolved dependencies, locking version numbers or Git commits. + -Reads and enforces locked versions and commits if a _shard.lock_ file is +Reads and enforces locked versions and commits if a *shard.lock* file is present. The *install* command may fail if a locked version doesn't match a requirement, but may succeed if a new dependency was added, as long as it -doesn't generate a conflict, thus generating a new _shard.lock_ file. +doesn't generate a conflict, thus generating a new *shard.lock* file. + -- ---frozen:: Strictly installs locked versions from _shard.lock_. Fails if _shard.lock_ is missing. ---without-development:: Does not install development dependencies. ---production:: same as _--frozen_ and _--without-development_ ---skip-postinstall:: Does not run postinstall of dependencies. +*--frozen*:: Strictly installs locked versions from *shard.lock*. Fails if *shard.lock* is missing. +*--without-development*:: Does not install development dependencies. +*--production*:: same as _--frozen_ and _--without-development_ +*--skip-postinstall*:: Does not run postinstall of dependencies. -- -*list* [--tree]:: +*list [--tree]*:: Lists the installed dependencies and their versions. + -Specifying _--tree_ arranges nested dependencies in a tree, instead of a flattened list. +Specifying *--tree* arranges nested dependencies in a tree, instead of a flattened list. -*lock* [--update [...]]:: -Resolves dependencies and creates or updates the _shard.lock_ file as per +*lock [--update [...]]*:: +Resolves dependencies and creates or updates the *shard.lock* file as per the *install* command, but never installs the dependencies. + -Specifying _--update_ follows the same semantics as the *update* +Specifying *--update* follows the same semantics as the *update* command. -*outdated* [--pre]:: +*outdated [--pre]*:: Lists dependencies that are outdated. + -When _--pre_ is specified, pre-release versions are also considered. +When *--pre* is specified, pre-release versions are also considered. *prune*:: -Removes unused dependencies from _lib_ folder. +Removes unused dependencies from *lib/* folder. -*update* [...]:: -Resolves and updates all dependencies into the _lib_ folder, -whatever the locked versions in the _shard.lock_ file. -Eventually generates a new _shard.lock_ file. +*update [...]*:: +Resolves and updates all dependencies into the *lib/* folder, +whatever the locked versions in the *shard.lock* file. +Eventually generates a new *shard.lock* file. + Specifying _shards_ will update these dependencies only, trying to be as conservative as possible with other dependencies, respecting the locked versions -in the _shard.lock_ file. +in the *shard.lock* file. -*version* [__]:: -Prints the current version of the shard located at _path_ (defaults to current +*version []*:: +Prints the current version of the shard located at *path* (defaults to current directory). To see the available options for a particular command, use *--help* after a command. -== GENERAL OPTIONS +== General Options ---version:: +*--version*:: Prints the version of _shards_. --h, --help:: +*-h*, *--help*:: Prints usage synopsis. ---no-color:: +*--no-color*:: Disables colored output. ---local:: +*--local*:: Don't update remote repositories, use the local cache only. --q, --quiet:: +*-q*, *--quiet*:: Decreases the log verbosity, printing only warnings and errors. --v, --verbose:: +*-v*, *--verbose*:: Increases the log verbosity, printing all debug statements. -== INSTALLATION +== Installation Shards is usually distributed with Crystal itself. Alternatively, a separate _shards_ package may be available for your system. To install from source, download or clone https://github.com/crystal-lang/shards[the repository] and run -*make CRFLAGS=--release*. The compiled binary is in _bin/shards_ and +*make CRFLAGS=--release*. The compiled binary is in *bin/shards* and should be added to *PATH*. -== Environment variables +== Environment Variables -SHARDS_OPTS:: +*SHARDS_OPTS*:: Allows general options to be passed in as environment variable. -*Example*: _SHARDS_OPTS="--no-color" shards update_ +*Example*: *SHARDS_OPTS="--no-color" shards update* -SHARDS_CACHE_PATH:: +*SHARDS_CACHE_PATH*:: Defines the cache location. In this folder, shards stores local copies of remote repositories. -Defaults to _.cache/shards_ in the home directory (_$XDG_CACHE_HOME_ or _$HOME_) +Defaults to *.cache/shards* in the home directory (*$XDG_CACHE_HOME* or *$HOME*) or the current directory. -SHARDS_INSTALL_PATH:: +*SHARDS_INSTALL_PATH*:: Defines the location where dependecies are installed. -Defaults to _lib_. +Defaults to *lib/*. -SHARDS_BIN_PATH:: +*SHARDS_BIN_PATH*:: Defines the location where executables are installed. -Defaults to _bin_. +Defaults to *bin/*. -CRYSTAL_VERSION:: +*CRYSTAL_VERSION*:: Defines the crystal version that dependencies should be resolved against. -Defaults to the output of _crystal env CRYSTAL_VERSION_. +Defaults to the output of *crystal env CRYSTAL_VERSION*. -SHARDS_OVERRIDE:: -Defines an alternate location of _shard.override.yml_. +*SHARDS_OVERRIDE*:: +Defines the location of *shard.override.yml*. == Files -shard.yml:: +*shard.yml*:: Describes a shard project including its dependencies. See *shard.yml*(5) for documentation. -shard.override.yml:: +*shard.override.yml*:: Allows overriding the source and restriction of dependencies. An alternative location can be configured with the env var *SHARDS_OVERRIDE*. + @@ -185,7 +185,7 @@ Use cases are local working copies, forcing a specific dependency version despite mismatching constraints, fixing a dependency, checking compatibility with unreleased dependency versions. -shard.lock:: +*shard.lock*:: Lockfile that stores information about the installed versions. + If your shard builds an application, *shard.lock* should be checked into version @@ -194,12 +194,12 @@ control to provide reproducible dependency installs. If it is only a library for other shards to depend on, *shard.lock* should _not_ be checked in, only *shard.yml*. It’s good advice to add it to *.gitignore*. -== REPORTING BUGS +== Reporting Bugs Report shards bugs to Crystal Language home page: -== COPYRIGHT +== Copyright Copyright © {localyear} Julien Portalier. http://www.apache.org/licenses/LICENSE-2.0[License Apache 2.0] @@ -207,8 +207,8 @@ http://www.apache.org/licenses/LICENSE-2.0[License Apache 2.0] This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. -== AUTHORS +== Authors Written by Julien Portalier and the Crystal project. -== SEE ALSO +== See Also *shard.yml*(5) diff --git a/man/shard.yml.5 b/man/shard.yml.5 index b3555f09..4b54a755 100644 --- a/man/shard.yml.5 +++ b/man/shard.yml.5 @@ -28,10 +28,10 @@ . LINKSTYLE blue R < > .\} .SH "NAME" -shard.yml \- metadata for projects managed by shards(1) +shard.yml \- metadata for projects managed by *shards*(1) .SH "DESCRIPTION" .sp -The file \fIshard.yml\fP is a YAML file with metadata about a project managed by shards, known as a \fBshard\fP. It must contain at least \fIname\fP and \fIversion\fP attributes plus optional additional attributes. +The file \fBshard.yml\fP is a YAML file with metadata about a project managed by shards, known as a \fBshard\fP. It must contain at least \fIname\fP and \fIversion\fP attributes plus optional additional attributes. .sp Both libraries and applications will benefit from \f(CRshard.yml\fP. .sp @@ -40,7 +40,7 @@ authors, description, license) than applications that may only have a name, vers dependencies. .SH "FORMAT" .sp -The file must be named \fIshard.yml\fP and be a valid YAML file with UTF\-8 encoding. +The file must be named \fBshard.yml\fP and be a valid YAML file with UTF\-8 encoding. It must not contain duplicate attributes in any mapping. It should use an indent of 2 spaces. It should not use advanced YAML features, only simple mappings, sequences and @@ -561,7 +561,7 @@ The URL may be [any protocol](\c supported by Git, which includes SSH, GIT and HTTPS. .sp The Git repository will be cloned, the list of versions (and associated -\fIshard.yml\fP) will be extracted from Git tags (e.g., \fIv1.2.3\fP). +\fBshard.yml\fP) will be extracted from Git tags (e.g., \fIv1.2.3\fP). .sp One of the other attributes (\fIversion\fP, \fItag\fP, \fIbranch\fP or \fIcommit\fP) is required. When missing, Shards will install the HEAD refs. @@ -693,7 +693,7 @@ Install the specified tag of a git dependency (string). .RE .SH "EXAMPLE:" .sp -Here is an example \fIshard.yml\fP for a library named \fIshards\fP at version \fI1.2.3\fP +Here is an example \fBshard.yml\fP for a library named \fIshards\fP at version \fI1.2.3\fP with some dependencies: .sp .if n .RS 4 diff --git a/man/shards.1 b/man/shards.1 index d0392a0f..d986650d 100644 --- a/man/shards.1 +++ b/man/shards.1 @@ -31,22 +31,22 @@ shards \- dependency manager for the Crystal Language .SH "SYNOPSIS" .sp -\fBshards\fP [\fI\fP...] [\fI\fP] [\fI\fP...] +\fBshards [...] [] [...]\fP .SH "DESCRIPTION" .sp Manages dependencies for Crystal projects and libraries with reproducible installs across computers and systems. .SH "USAGE" .sp -\fIshards\fP requires the presence of a \fIshard.yml\fP file in the project +\fIshards\fP requires the presence of a \fBshard.yml\fP file in the project folder (working directory). This file describes the project and lists dependencies that are required to build it. See \fBshard.yml\fP(5) for more -information on its format. A default file can be created by running \fIshards init\fP. +information on its format. A default file can be created by running \fBshards init\fP. .sp -Running \fIshards install\fP resolves and installs the +Running \fBshards install\fP resolves and installs the specified dependencies. The installed versions are written into a \fBshard.lock\fP file for using the exact same dependency versions when -running \fIshards install\fP again. +running \fBshards install\fP again. .sp If your shard builds an application, both \fBshard.yml\fP and \fBshard.lock\fP should be checked into version control to provide reproducible @@ -58,16 +58,16 @@ advice to add it to \fB.gitignore\fP. .sp If no \fIcommand\fP is given, \fBinstall\fP command will be run by default. .sp -To see the available options for a particular command, use \fI\-\-help\fP after the command. +To see the available options for a particular command, use \fB\-\-help\fP after the command. .sp -\fBbuild\fP [\fI\fP] [\fI\fP...] +\fBbuild [] [...]\fP .RS 4 -Builds the specified \fI\fP in \fBbin\fP path. If no targets are specified, +Builds the specified \fBtargets\fP in \fBbin/\fP path. If no targets are specified, all are built. This command ensures all dependencies are installed, so it is not necessary to run \fBshards install\fP before. .sp -All \fI\fP following the command are delegated to \fBcrystal build\fP. +All \fBbuild_options\fP following the command are delegated to \fBcrystal build\fP. .RE .sp \fBcheck\fP @@ -76,96 +76,90 @@ Verifies that all dependencies are installed and requirements are satisfied. .sp Exit status: .sp -\fB0\fP -.RS 4 -Dependencies are satisfied. -.RE +\fB0\fP: Dependencies are satisfied. .sp -\fB1\fP -.RS 4 -Dependencies are not satisfied. -.RE +\fB1\fP: Dependencies are not satisfied. .RE .sp \fBinit\fP .RS 4 -Initializes a default \fIshard.yml\fP in the current folder. +Initializes a default \fBshard.yml\fP in the current folder. .RE .sp -\fBinstall\fP [\-\-frozen] [\-\-without\-development] [\-\-production] [\-\-skip\-postinstall] +\fBinstall [\-\-frozen] [\-\-without\-development] [\-\-production] [\-\-skip\-postinstall]\fP .RS 4 -Resolves and installs dependencies into the \fIlib\fP folder. If not already -present, generates a \fIshard.lock\fP file from resolved dependencies, locking +Resolves and installs dependencies into the \fBlib/\fP folder. If not already +present, generates a \fBshard.lock\fP file from resolved dependencies, locking version numbers or Git commits. .sp -Reads and enforces locked versions and commits if a \fIshard.lock\fP file is +Reads and enforces locked versions and commits if a \fBshard.lock\fP file is present. The \fBinstall\fP command may fail if a locked version doesn\(cqt match a requirement, but may succeed if a new dependency was added, as long as it -doesn\(cqt generate a conflict, thus generating a new \fIshard.lock\fP file. +doesn\(cqt generate a conflict, thus generating a new \fBshard.lock\fP file. .sp -\-\-frozen +\fB\-\-frozen\fP .RS 4 -Strictly installs locked versions from \fIshard.lock\fP. Fails if \fIshard.lock\fP is missing. +Strictly installs locked versions from \fBshard.lock\fP. Fails if \fBshard.lock\fP is missing. .RE .sp -\-\-without\-development +\fB\-\-without\-development\fP .RS 4 Does not install development dependencies. .RE .sp -\-\-production +\fB\-\-production\fP .RS 4 same as \fI\-\-frozen\fP and \fI\-\-without\-development\fP .RE .sp -\-\-skip\-postinstall +\fB\-\-skip\-postinstall\fP .RS 4 Does not run postinstall of dependencies. .RE .RE .sp -\fBlist\fP [\-\-tree] +\fBlist [\-\-tree]\fP .RS 4 Lists the installed dependencies and their versions. .sp -Specifying \fI\-\-tree\fP arranges nested dependencies in a tree, instead of a flattened list. +Specifying \fB\-\-tree\fP arranges nested dependencies in a tree, instead of a flattened list. .RE .sp -\fBlock\fP [\-\-update [...]] +\fBlock [\-\-update [...]]\fP .RS 4 -Resolves dependencies and creates or updates the \fIshard.lock\fP file as per +Resolves dependencies and creates or updates the \fBshard.lock\fP file as per the \fBinstall\fP command, but never installs the dependencies. .sp -Specifying \fI\-\-update\fP follows the same semantics as the \fBupdate\fP +Specifying \fB\-\-update\fP follows the same semantics as the \fBupdate\fP command. .RE .sp -\fBoutdated\fP [\-\-pre] +\fBoutdated [\-\-pre]\fP .RS 4 Lists dependencies that are outdated. .sp -When \fI\-\-pre\fP is specified, pre\-release versions are also considered. +When \fB\-\-pre\fP is specified, pre\-release versions are also considered. .RE .sp \fBprune\fP .RS 4 -Removes unused dependencies from \fIlib\fP folder. +Removes unused dependencies from \fBlib/\fP folder. .RE .sp -\fBupdate\fP [...] +\fBupdate [...]\fP .RS 4 -Resolves and updates all dependencies into the \fIlib\fP folder, -whatever the locked versions in the \fIshard.lock\fP file. -Eventually generates a new \fIshard.lock\fP file. +Resolves and updates all dependencies into the \fBlib/\fP folder, +whatever the locked versions in the \fBshard.lock\fP file. +Eventually generates a new \fBshard.lock\fP file. .sp Specifying \fIshards\fP will update these dependencies only, trying to be as conservative as possible with other dependencies, respecting the locked versions -in the \fIshard.lock\fP file. +in the \fBshard.lock\fP file. .RE .sp -\fBversion\fP [\fI\fP] +\fBversion []\fP .RS 4 -Prints the current version of the shard located at \fIpath\fP (defaults to current +Prints the current version of the shard located at \fBpath\fP (defaults to current directory). .RE .sp @@ -173,37 +167,37 @@ To see the available options for a particular command, use \fB\-\-help\fP after a command. .SH "GENERAL OPTIONS" .sp -\-\-version +\fB\-\-version\fP .RS 4 Prints the version of \fIshards\fP. .RE .sp -\-h, \-\-help +\fB\-h\fP, \fB\-\-help\fP .RS 4 Prints usage synopsis. .RE .sp -\-\-no\-color +\fB\-\-no\-color\fP .RS 4 Disables colored output. .RE .sp -\-\-local +\fB\-\-local\fP .RS 4 Don\(cqt update remote repositories, use the local cache only. .RE .sp -\-\-ignore\-crystal\-version +\fB\-\-ignore\-crystal\-version\fP .RS 4 Do not enforce crystal version restrictions on shards. .RE .sp -\-q, \-\-quiet +\fB\-q\fP, \fB\-\-quiet\fP .RS 4 Decreases the log verbosity, printing only warnings and errors. .RE .sp -\-v, \-\-verbose +\fB\-v\fP, \fB\-\-verbose\fP .RS 4 Increases the log verbosity, printing all debug statements. .RE @@ -215,60 +209,60 @@ separate \fIshards\fP package may be available for your system. To install from source, download or clone .URL "https://github.com/crystal\-lang/shards" "the repository" " " and run -\fBmake CRFLAGS=\-\-release\fP. The compiled binary is in \fIbin/shards\fP and +\fBmake CRFLAGS=\-\-release\fP. The compiled binary is in \fBbin/shards\fP and should be added to \fBPATH\fP. .SH "ENVIRONMENT VARIABLES" .sp -SHARDS_OPTS +\fBSHARDS_OPTS\fP .RS 4 Allows general options to be passed in as environment variable. -\fBExample\fP: \fISHARDS_OPTS="\-\-ignore\-crystal\-version" shards update\fP +\fBExample\fP: \fBSHARDS_OPTS="\-\-ignore\-crystal\-version" shards update\fP .RE .sp -SHARDS_CACHE_PATH +\fBSHARDS_CACHE_PATH\fP .RS 4 Defines the cache location. In this folder, shards stores local copies of remote repositories. -Defaults to \fI.cache/shards\fP in the home directory (\fI$XDG_CACHE_HOME\fP or \fI$HOME\fP) +Defaults to \fB.cache/shards\fP in the home directory (\fB$XDG_CACHE_HOME\fP or \fB$HOME\fP) or the current directory. .RE .sp -SHARDS_INSTALL_PATH +\fBSHARDS_INSTALL_PATH\fP .RS 4 Defines the location where dependecies are installed. -Defaults to \fIlib\fP. +Defaults to \fBlib/\fP. .RE .sp -SHARDS_BIN_PATH +\fBSHARDS_BIN_PATH\fP .RS 4 Defines the location where executables are installed. -Defaults to \fIbin\fP. +Defaults to \fBbin/\fP. .RE .sp -CRYSTAL_VERSION +\fBCRYSTAL_VERSION\fP .RS 4 Defines the crystal version that dependencies should be resolved against. -Defaults to the output of \fIcrystal env CRYSTAL_VERSION\fP. +Defaults to the output of \fBcrystal env CRYSTAL_VERSION\fP. .RE .sp -SHARDS_OVERRIDE +\fBSHARDS_OVERRIDE\fP .RS 4 -Defines the location of \fIshard.override.yml\fP. +Defines the location of \fBshard.override.yml\fP. .RE .SH "FILES" .sp -shard.yml +\fBshard.yml\fP .RS 4 Describes a shard project including its dependencies. See \fBshard.yml\fP(5) for documentation. .RE .sp -shard.override.yml +\fBshard.override.yml\fP .RS 4 -Local overrides to \fIshard.yml\fP. +Local overrides to \fBshard.yml\fP. .RE .sp -shard.lock +\fBshard.lock\fP .RS 4 Lockfile that stores information about the installed versions. .sp