permalink | copyright |
---|---|
README.html |
Copyright (c) 2010-2021 K Team. All Rights Reserved. |
The K Framework is a tool for designing and modeling programming languages and software/hardware systems. At the core of the K Framework is a programming, modeling, and specification language called K. The K Framework includes tools for compiling K specifications to build interpreters, model checkers, verifiers, associated documentation, and more.
This is a readme file for K developers. Users should feel comfortable using the command line, as we do not provide GUI tools at this time.
K-based tool users should:
- Consult their tool documentation for build/installation instructions.
- If needed, download a packaged release of the K Framework as part of their tool setup process.
If you are interested in quickly trying out the K Framework without building from source, please see our packaged release installation guide.
The rest of this file assumes you intend to build and install the K Framework from source.
Note that the K Framework can only be built on (x86-64) Linux-like systems, e.g., this also includies macOS/brew (x86-64) as well as the Windows Subsystem for Linux. All 32-bit systems are not supported. See the installation notes for details about supported configurations and system setup.
- Prerequisite Install Guide
- Build and Install Guide
- IDE Setup
- Running the Test Suite
- Changing the KORE Data Structures
- Building the Final Release Directory/Archives
- Compiling Definitions and Running Programs
- Troubleshooting
Before building and installing the K Framework, the following prerequisites must first be installed.
On Ubuntu Linux:
git submodule update --init --recursive
sudo apt-get install build-essential m4 openjdk-8-jdk libgmp-dev libmpfr-dev pkg-config flex bison z3 libz3-dev maven python3 cmake gcc clang-8 lld-8 llvm-8-tools zlib1g-dev libboost-test-dev libyaml-dev libjemalloc-dev
curl -sSL https://get.haskellstack.org/ | sh
Note: we require version 8 or greater for clang, lld, and llvm-tools.
On Arch Linux:
git submodule update --init --recursive
sudo pacman -S git maven jdk-openjdk cmake boost libyaml jemalloc clang llvm lld zlib gmp mpfr z3 curl stack base-devel base python
If you install this list of dependencies, continue directly to the Build and Install Guide.
The following dependencies are needed either at build time or runtime:
- bison
- boost
- cmake
- flex
- gcc
- gmp
- jdk (version 8u45 or greater)
- libjemalloc
- libyaml
- llvm (We require version 8 or greater for clang, lld, and llvm-tools. On some distributions, the utilities below are also needed and packaged separately.)
- make
- maven
- mpfr
- pkg-config
- python
- stack
- zlib
- z3 (on some distributions libz3 is also needed and packaged separately) Note that you need at least version 4.6 of Z3, and we recommend at least version 4.8.
The following dependencies are optional and are only needed when building the OCaml backend (not recommended):
Typically, these can all be installed from your package manager. On some system configurations, special installation steps or post-installation configuration steps are required. See the notes below.
-
Java Development Kit (required JDK8 version 8u45 or higher)
-
Linux: Download from package manager (e.g.
sudo apt-get install openjdk-8-jdk
). -
macOS/brew: Download from package manager (e.g.
brew install java
).
To make sure that everything works you should be able to call
java -version
andjavac -version
from a terminal. -
-
LLVM
- macOS/brew: Since LLVM is distributed as a keg-only package, we must
explicitly make it available for command line usage. See the results
of the
brew info llvm
command for more information on how to do this.
- macOS/brew: Since LLVM is distributed as a keg-only package, we must
explicitly make it available for command line usage. See the results
of the
-
Apache Maven
-
Linux: Download from package manager (e.g.
sudo apt-get install maven
). -
macOS/brew: Download it from a package manager or from http://maven.apache.org/download.cgi and follow the instructions on the webpage.
Maven usually requires setting an environment variable
JAVA_HOME
pointing to the installation directory of the JDK (not to be mistaken with JRE).You can test if it works by calling
mvn -version
in a terminal. This will provide the information about the JDK Maven is using, in case it is the wrong one. -
-
Haskell Stack
To install, go to https://docs.haskellstack.org/en/stable/README/ and follow the instructions. You may need to do
stack upgrade
to ensure the latest version of Haskell Stack.
Checkout the project source at your desired location and call mvn package
from the main directory to build the distribution. For convenient usage, you
can update your $PATH
with
<checkout-dir>/k-distribution/target/release/k/bin
(strongly recommended, but optional).
You are also encouraged to set the environment variable MAVEN_OPTS
to
-XX:+TieredCompilation
, which will significantly speed up the incremental
build process.
If you want to use the OCaml backend (not recommended), then after running
mvn package
for the first time, setup the OCaml dependencies by running
the following command:
k-distribution/target/release/k/bin/k-configure-opam
eval $(opam config env)
This performs first-time setup of the OCaml backend. You may optionally set
OPAMROOT
before running this command to specify where any OCaml dependencies
should be installed.
To build the K Framework itself, run:
nix-build -A k
The various backends are provided as separate packages:
nix-build -A llvm-backend
nix-build -A haskell-backend
To run the integration tests:
nix-build test.nix
You can enter a development environment for working on the K Framework frontend by running:
nix-shell
To create a development environment for a project that depends on the K
Framework, you can add a shell.nix
based on this template:
# shell.nix
let
kframework = import ./path/to/k {};
inherit (kframework) mkShell;
in
mkShell {
buildInputs = [
kframework.k
clang kframework.llvm-backend
kframework.haskell-backend
];
}
If you change any pom.xml
, you must run ./nix/update-maven.sh
.
You should run K from the k-distribution project, because it is the only project to have the complete classpath and therefore all backends.
N.B. the Eclipse internal compiler may generate false compilation errors (there are bugs in its support of Scala mixed compilation). We recommend using IntelliJ IDEA if at all possible.
To autogenerate an Eclipse project for K, run mvn install -DskipKTest; mvn eclipse:eclipse
on the
command line, and then go into each of the kore
and tiny
directories and run sbt eclipse
.
Then start eclipse and go to File->Import->General->Existing projects into workspace, and select
the directory of the installation. You should only add the leaves to the workspace, because
eclipse does not support hierarchical projects.
IntelliJ IDEA comes with built-in maven integration. For more information, refer to the IntelliJ IDEA wiki
To completely test the current version of the K framework, run mvn verify
.
This normally takes roughly 30 minutes on a fast machine. If you are interested only
in running the unit tests and checkstyle goals, run mvn verify -DskipKTest
to
skip the lengthy ktest
execution.
If you need to change the KORE data structures (unless you are a K core developer, you probably do not), see Guide-for-changing-the-KORE-data-structures.
Call mvn install
in the base directory. This will attach an artifact to the local
maven repository containing a zip and tar.gz of the distribution.
The functionality to create a tagged release is currently incomplete.
Assuming k-distribution/target/release/k/bin is in your path, you can compile definitions using
the kompile
command. To execute a program you can use krun
.
For running either program in the debugger, use the main class org.kframework.main.Main
with an additional argument -kompile
or -krun
added before other command line arguments, and use the classpath from the k-distribution
module.
Common build-time error messages:
-
Error: JAVA_HOME not found in your environment. Please set the JAVA_HOME variable in your environment to match the location of your Java installation.
- Make sure
JAVA_HOME
points to the JDK and not the JRE directory.
- Make sure
-
[WARNING] Cannot get the branch information from the git repository: Detecting the current branch failed: 'git' is not recognized as an internal or external command, operable program or batch file.
git
might not be installed on your system. Make sure that you can executegit
from the command line.
-
1) Error injecting constructor, java.lang.Error: Unresolved compilation problems: The import org.kframework.parser.outer.Outer cannot be resolved Outer cannot be resolved
- You may run into this issue if target/generated-sources/javacc is not added to the build path of your IDE. Generally this is solved by regenerating your project / re-syncing it with the pom.xml.
-
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.1:compile (default-compile) on project k-core: Fatal error compiling: invalid target release: 1.8 -> [Help 1]
- You either do not have Java 8 installed, or
$JAVA_HOME
does not point to a Java 8 JDK.
- You either do not have Java 8 installed, or
-
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-antrun-plugin:1.7:run (build-haskell) on project haskell-backend: An Ant BuildException has occured: exec returned: 1
and scrolling up, you see an error message similar to:
[exec] Installing GHC ... [exec] ghc-pkg: Couldn't open database $HOME/.stack/programs/x86_64-linux/ghc-tinfo6-8.10.1/lib/ghc-8.10.1/package.conf.d for modification: {handle: $HOME/.stack/programs/x86_64-linux/ghc-tinfo6-8.10.1/lib/ghc-8.10.1/package.conf.d/package.cache.lock}: hLock: invalid argument (Invalid argument)
- If you are using a WSL version 1 environment,
then you have encountered a known issue with the latest versions of GHC. In this
case, please either:
- upgrade to WSL version 2,
- install a packaged release for your WSL version 1 distribution,
- switch to a supported system configuration (e.g. Linux on a virtual machine), or
- if you do not need the symbolic execution capabilities of the K Framework, disable them
at build time (and remove the GHC dependency) by doing:
mvn package -Dhaskell.backend.skip
.
- If you are using a WSL version 1 environment,
then you have encountered a known issue with the latest versions of GHC. In this
case, please either:
If something unexpected happens and the project fails to build, try mvn clean
and
rebuild the entire project. Generally speaking, however, the project should build incrementally
without needing to be cleaned first.
If you are doing work with snapshot dependencies, you can update them to the latest version by
running maven with the -U
flag.
If you are configuring artifacts in a repository and need to purge the local repository's cache
of artifacts, you can run mvn dependency:purge-local-repository
.
If tests fail but you want to run the build anyway to see what happens, you can use mvn package -DskipTests
.
If you still cannot build, please contact a K developer.