Name: Mechanic
Owner: F# Community Project Incubation Space
Description: null
Created: 2018-01-01 13:37:28.0
Updated: 2018-05-10 18:55:26.0
Pushed: 2018-04-18 15:13:15.0
Homepage: null
Size: 1174
Language: F#
GitHub Committers
User | Most Recent Commit | # Commits |
---|
Other Committers
User | Most Recent Commit | # Commits |
---|
The F# compiler needs to get files passed in correct order for compilation, so that everything is declared before usage. There are some different opinions if this should be seen as a feature or as a limitation. This project won't settle this dispute, but it wants to make it easier for F# developers to maintain that order in fsproj files.
The idea is to create a dotnet core tool that uses the FSharp.Compiler.Service to find a valid file order. Since there may exist more than one valid order, the tool will write the order into the F# project file (the fsproj file). The user will then commit the fsproj into version control and build servers will use exactly the one committed version. In contrast to multi-pass compilers this will remain a step that is done explicitly by the programmer and there always needs to be at least one valid order. In this sense the tool and the fsproj are very similar to paket and the paket.lock file.
In addition to creating a standalone dotnet core CLI tool, we would probably also want to create a standalone library that could be integrated into editors. This would make integration a little simpler and could also take advantage of existing FSharp.Compiler.Service caches. In this case, we would probably want to take an exisiting FSharpChecker instance as a parameter.
This depends a lot on how much information we get from the FSharp.Compiler.Service. But the following properties should hold:
Algorithm discussion at #10
Current algorithm documentation here.
In real world editing scenarios we will hardly ever need to reorder the whole file list. Usually programmers already have a working state and perform changes to it. These changes may introduce small ordering issues or even circular dependencies and the tool should help to resolve these. The following commands seem to be useful:
In order to test the tool you can clone the repo and run the following command:
dotnet run -p src/Mechanic.CommandLine [path/to/a/projectfile.fsproj]
Advanced usage:
USAGE: [--help] [--pattern <string> <string>] [--dry-run] [--log-ast-tree] [--log-collected-symbols] [--log-file-dependencies]
[--log-file-dependencies-with-symbols] [<string>]
<string> Project file.
OPTIONS:
--pattern <string> <string>
Alternative to project file - specify directory and wildcard pattern. Only print out resulting order.
--dry-run Don't update project file.
--shuffle-test Do extensive testing of the correctness of Mechanic on given project.
Tries varoius order of source files and check Mechanic result by compiler.
--log-ast-tree Print out AST tree for each source file from project.
--log-collected-symbols
Print out collected symbols for each source file from project.
--log-file-dependencies
Print out file dependencies in project.
--log-file-dependencies-with-symbols
Print out file dependencies (with depended symbols) in project.
The following toolchain is implemented to get us started:
To build the project and run the tests, simply run one of the build scripts,
depending on your environment; build.ps1
, build.sh
(with the --use-mono
flag if under non-Windows)
or build.cmd
.
In the future, we might also want to use e.g.
This project will be done mostly by newcomers to the F# OSS ecosystem. This is an explicit decision in order to get more people involved. Long time members of the F# OSS sphere will mentor and try to help if things get stuck.
If you are interested in joining this project, then welcome! We are really interested in bringing new people into the F# OSS ecosystem. Don't be shy! One way to get started is to take a look at the list of issues to see if there is anything there you feel like you'd like to contribute with. There's a couple of ongoing discussions on how to structure the library, and especially #10 has some details on where the code base might be heading.