在线时间:8:00-16:00
迪恩网络APP
随时随地掌握行业动态
扫描二维码
关注迪恩网络微信公众号
开源软件名称(OpenSource Name):kowainik/stan开源软件地址(OpenSource Url):https://github.com/kowainik/stan开源编程语言(OpenSource Language):Haskell 79.3%开源软件介绍(OpenSource Introduction):StanStan is a Haskell STatic ANalysis tool.
Table of Contents
What this tool is about[Back to the Table of Contents] ↑ Stan is a command-line tool for analysing Haskell projects. It discovers which parts of the code can potentially be improved, and offers suggestions on how to do so. Stan is searching for not only performance or error-prone code pieces, but it also can help with establishing and applying best-practices from the whole Haskell ecosystem. Although Haskell is a statically typed language, not all properties can be encoded in types. Even though GHC is quite a powerful compiler, it tries to be library-agnostic and provide only language-specific suggestions, while Stan uses the knowledge about the current state of the ecosystem and commonly used libraries. You will find Stan helpful if you enjoy writing in Haskell, but want more guarantees from your code, not provided by the Haskell type system or GHC. For a crash course to Stan, watch the talk about Stan, presented by Veronika Romashkina and Dmitrii Kovanikov at the Haskell Love conference. Goals[Back to the Table of Contents] ↑ Stan design and implementation is driven by the following goals:
Features[Back to the Table of Contents] ↑ Stan is a configurable CLI tool. Besides the main feature of analysing Haskell projects statically, Stan has a list of features that make it unique, easy to use and flexible to configure:
You can see an example of Stan HTML report hosted online here: The below example of the terminal output gives you the understanding of what sorts of analysis you can expect from Stan: How it works[Back to the Table of Contents] ↑ Stan analysis is based on the HIE files — compile-time information about Haskell source code gathered and recorded by GHC. The HIE files contain the Haskell AST, detailed information about each identifier and types of all expressions and sub-expressions. GHC does a huge amount of work when compiling the Haskell projects, and Stan takes advantage of this feature to avoid duplicating the work and focus more on the unique features. To analyse HIE files easily, we developed an eDSL for defining AST and Type patterns based on the final tagless approach. Stan algorithm traverses HIE AST for each HIE file in the project, and matches every AST node with the given pattern to find potential improvement areas in the code. Each Stan analysis check is represented by the inspection with the unique ID. Each inspection has a name, description, severity, list of categories, pattern for matching relevant parts of source code and possible solutions to the problem. When an inspection is casted on the project, it produces zero or more observations —. You can think of an observation as a pair of an inspection and a piece of source code where this inspection was triggered. Each observation is assigned an unique stable ID depending on the source location, so you can refer to them later or ignore. You can disable inspections or enable them only in particular modules
using check — rules for controlling which inspections to run and
where. Each check has a type ( If you want to understand Stan terminology better, refer to the glossary: Installation instructions[Back to the Table of Contents] ↑ Stan takes advantage of the GHC API to provide its analysis. Because of this, Stan and the analysed project need to be built with the same GHC version (for more details see #178). That is why the easiest and most robust way to install Stan is to build it from sources on your machine.
Using Cabal[Back to the Table of Contents] ↑ Below are the steps to install Stan using the Cabal build tool.
First, you need to clone the repository: $ git clone https://github.com/kowainik/stan.git
$ cd stan Then, you need to build it using Cabal: $ cabal v2-build exe:stan Finally, you can copy the resulting executable under the desired location (that should be under the PATH environment variable), like so: $ cp "$(cabal v2-exec --verbose=0 --offline sh -- -c 'command -v stan')" ~/.local/bin/stan Using Stack[Back to the Table of Contents] ↑ Below are the steps to install Stan using the Stack build tool.
First, you need to clone the repository. $ git clone https://github.com/kowainik/stan.git
$ cd stan Then, you need to build it using Stack: $ stack build Finally, you can copy the resulting executable under the desired location (that should be under the PATH environment variable), like so: $ cp "$(stack path --local-install-root)/bin/stan" ~/.local/bin/stan Hackage[Back to the Table of Contents] ↑ Stan is available on Hackage. You can install the tool from there as well: $ cabal v2-install stan --install-method=copy --overwrite-policy=always You can also choose with which GHC version you want to have Stan installed, and optionally add some suffix to the executable name: $ cabal v2-install stan \
-w ghc-8.10.1 \
--install-method=copy \
--overwrite-policy=always \
--program-suffix=-8.10.1 Homebrew[Back to the Table of Contents] ↑ If you are on MacOS, you can get Stan using Homebrew Kowainik's Tap. You need to run the following command for that: $ brew install kowainik/tap/stan
Ubuntu PPA[Back to the Table of Contents] ↑ If you are on Ubuntu, you can get Stan using Kowainik's PPA. You need to run the following commands for that: $ sudo add-apt-repository ppa:kowainik/stan
$ sudo apt update
$ sudo apt install stan
Download binary[Back to the Table of Contents] ↑ You can download binary directly from GitHub releases. After downloading binary, make it executable and copy it under convenient location, e.g.: $ chmod +x stan-0.0.1.0-Linux-ghc-8.10.1
$ mv stan-0.0.1.0-Linux-ghc-8.10.1 ~/.local/bin/stan
Usage instructions[Back to the Table of Contents] ↑ Stan works with the HIE files to analyse Haskell
projects. Therefore, Stan requires users to generate HIE files in
advance. Fortunately, it is straightforward to satisfy this
necessity. To produce HIE files, add the following GHC options in your
project's ghc-options: -fwrite-ide-info
-hiedir=.hie
After creating HIE files, you can just run Stan on the project: $ stan to see all found suggestions in your terminal. If you want to see a more detailed information in a more structured
way, you can generate an HTML report (to the $ stan report Stan strives to implement the convenient interface, so you can use the tool without configuring a lot in advance. However, the tool also provides various ways to set it up in the way to be the most efficient with your particular use case. General configuration info[Back to the Table of Contents] ↑ Stan's work can be configured from the multiple sources (in increasing order of priority):
Stan runtime settings have many parts, and each of them can come from different configuration sources. If some option is specified through multiple sources, the most prioritized one will be used. In addition, Stan helps to understand its own configuration, so it outputs detailed information about each part of the config, what configuration settings were used and how they were set. TOML configurations[Back to the Table of Contents] ↑ Stan supports TOML runtime configuration in order to customize the work of the tool based on the user's individual requirements. You can use the TOML configuration to disable some inspections, enable them only in particular Haskell modules, ignore some observations or completely remove some files from the analysis. Specifically, you can use the following variables to set up custom configurations with TOML:
See Haddock documentation for explanation of how the TOML configuration works and examples of the different use cases. In case you have a number of TOML files locally, the following rules describe how Stan decides which TOML configuration file to use:
Command-line Interface[Back to the Table of Contents] ↑ This section describes what is possible to achieve with the Stan CLI. If you have already installed the analyser, you can use $ stan --help to get the short information of all possible commands and options in your terminal. Main command[Back to the Table of Contents] ↑ The main command is the one that actually would analyse the Haskell codebase. There are plenty of configurations and options you can tune for each run (similarly to the TOML configurations):
Here is the high-level explanation of the available sub-commands:
More precisely the commands and options are described in here:
For example, if you want to run Stan analysis only on a single file, generate the HTML report and immediately open report in a browser, you can use the following command: $ stan check --exclude --filter-all --scope-all \
check --include --filter-all --file=src/Stan/Example.hs \
report --browse Inspections[Back to the Table of Contents] ↑ You can find the list of all available inspections with description
and additional information on our
dedicated wiki page. However, with the tool you can get
this information easily by using the
Converting between TOML and CLI configurations[Back to the Table of Contents] ↑ It is usually convenient to have a proper configuration file that suits your project, which you can reuse each run of the Stan. But sometimes you need to quickly run the tool with the same settings on another machine where having such files is not possible. Or you want to send the reproducible command, that anyone could execute and get the identical results. For these purposes, we have a special command that allows you to do so:
And for convenience you are able to use the reversed command ––
Other tools[Back to the Table of Contents] ↑
To learn more about the implementation and goals of our project, please read the sections above that describe the Stan project in detail. Roadmap[Back to the Table of Contents] ↑ Our plan for the nearest future:
We have much more ideas to work on. See more detailed plan in the dedicated GitHub Project page. UsersStan is known to be adopted by the following companies: Links to Wiki[Back to the Table of Contents] ↑ |
2023-10-27
2022-08-15
2022-08-17
2022-09-23
2022-08-13
请发表评论