Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/commercialhaskell/stack-templates

Project templates for stack new
https://github.com/commercialhaskell/stack-templates

Last synced: about 2 hours ago
JSON representation

Project templates for stack new

Awesome Lists containing this project

README 

        
## Project templates for Stack



From Stack 1.9.1, Stack allows any GitHub, GitLab or Bitbucket repository named

`stack-templates` to provide project templates for Stack. For example, a

template file at `username/stack-templates/my-template.hsfiles` on GitHub can be

identified as `username/my-template` when using `stack new`. For more

information see the output of the `stack templates` command and its

[documentation](https://docs.haskellstack.org/en/stable/templates_command/).



This repository provides the project template `new-template`, which is the

default template used by `stack new`. It also provides `STACK_HELP.md`, which

specifies the output of the `stack templates` command.



This repository is the default one used by Stack and it provides 24 other

project templates. Information about some of those templates is included in

`template-info.yaml` and this repository's Wiki.



Those project templates are maintained but this repository is not accepting new

templates because of the difficulties in maintaining large numbers of templates

centrally.



This repository's Wiki provides a place where the Haskell community can

announce the availability of project templates at other locations.



## License



All the templates in this repository use identifiers from the

[SPDX License List](https://spdx.org/licenses/) and all but two specify

`BSD-3-Clause`.



The SPDX expression syntax was first required by the Cabal

Package Description Format Specification version 2.2 and that version is

specified in template Cabal files. Hpack will also detect that the use of

`BSD-3-Clause` in a template `package.yaml` file requires `cabal-version: 2.2`

in a Cabal file.



Stack, however, also supports versions of GHC that come with versions of the

`Cabal` library before `Cabal-2.2.0.0`. If you are using such versions of GHC,

edit the files produced by the template to replace `BSD-3-Clause` with `BSD3`

and edit any Cabal files produced by the template to replace

`cabal-version: 2.2` with `cabal-version: >=1.10`.



## Project template format



Each project template is specified in an `.hsfiles` file, using the syntax of

the [Mustache](https://mustache.github.io/mustache.1.html) tool.



Each file to be generated by the project template is specified with

`START_FILE`, like this:



```

{-# START_FILE {{name}}.cabal #-}

name:                {{name}}

version:             0.1.0.0

...

```



Parameters to the template are written `{{foo}}`. They are provided by users via

their Stack `config.yaml` file, like this:



``` yaml

templates:

  params:

    author-email: [email protected]

    author-name: Chris Done

    copyright: 2023 Chris Done

    github-username: chrisdone

    category: Development

```



When the user runs `stack new my-project username/your-template` and they do not

have the parameters provided in their Stack `config.yaml`, Stack will warn the

user that such parameters were missing, like this:



```

Downloading template username/your-template to create project my-project in

directory my-project/ ...

Downloaded .



Note: The following parameters were needed by the template but not provided:

      author-email, and author-name.



      You can provide them in Stack's global YAML configuration file

      () like this:



      templates:

        params:

          author-email: value

          author-name: value



      Or you can pass each one on the command line as parameters like this:



      stack new my-project username/your-template -p "author-email:value"

      -p "author-name:value"

```



The output of the template will yield a blank space where your parameter was. If

you want to provide default values for your template parameters, use this

Mustache syntax:



```

author:              {{author-name}}{{^author-name}}Author name here{{/author-name}}

```



## Related initiatives



The repository https://github.com/prikhi/stack-templatizer (unconnected with

this repository) provides Haskell source code to build an application that

will generate an `.hsfiles` file from the contents of a folder.



## Yesod templates



The Yesod templates are generated from the

[yesod-scaffold repo](https://github.com/yesodweb/yesod-scaffold). Please

send pull requests for those templates to that repository instead of this one.