From dfa49f8c3caf4b4252f1a10fb1cc772d7ee63ce2 Mon Sep 17 00:00:00 2001 From: alex28sh Date: Tue, 20 Aug 2024 22:45:22 +0200 Subject: [PATCH] README.rst --- README.rst | 113 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 README.rst diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..51d0ee3 --- /dev/null +++ b/README.rst @@ -0,0 +1,113 @@ + +Nagini is an automatic verifier for statically typed Python programs, based on the `Viper `_ verification infrastructure. Nagini is being developed at the `Programming Methodology Group `_ at ETH Zurich. + +Our CAV 2018 tool paper describing Nagini can be found `here `_, and a more detailed description of its encoding can be found in `Marco Eilers' thesis `_. Also see `the Wiki `_ for the documentation of Nagini's specification language. + +Dependencies (Ubuntu Linux) +=================================== + +Install Java 11 or newer (64 bit) and Python 3.8 (64 bit, newer versions likely *will not work*) and the required libraries. +For usage with Viper's verification condition generation backend Carbon, you will also need to install Boogie (version 2.15.9). + +Dependencies (Windows) +========================== + +1. Install Java 11 or newer (64 bit) and Python 3.8 (64 bit, newer versions likely *will not work*). + +2. Install the required version of either Visual C++ Build Tools or Visual Studio. + + +Getting Started +=============== + +1. Create a virtual environment:: + + virtualenv --python=python3 + +2. Activate it:: + + source env/bin/activate + +3. Install Nagini:: + + pip install nagini + + Alternatively, to get the most up-to-date version, install from source; this will require manually getting and compiling Viper (most likely the most recent development version):: + + git clone https://github.com/marcoeilers/nagini.git + cd nagini + pip install . + +4. Optionally, try running the tests:: + + pytest src/nagini_translation/tests.py --silicon + +Command Line Usage +================== + +To verify a specific file from the nagini directory, run:: + + nagini [OPTIONS] path-to-file.py + + +The following command line options are available:: + + --verifier + Selects the Viper backend to use for verification. + Possible options are 'silicon' (for Symbolic Execution) and 'carbon' + (for Verification Condition Generation based on Boogie). + Default: 'silicon'. + + --select + Select which functions/methods/classes to verify. Expects a comma- + separated list of names. + + --counterexample + Enable outputting counterexamples for verification errors (experimental). + + --sif=v + Enable verification of secure information flow. v can be true for ordinary + non-interference (for sequential programs only), poss for possiblistic + non-intererence (for concurrent programs) or prob for probabilistic non- + interference (for concurrent programs). + + --z3 + Sets the path of the Z3 executable. Alternatively, the + 'Z3_EXE' environment variable can be set. + + --boogie + Sets the path of the Boogie executable. Required if the Carbon backend + is selected. Alternatively, the 'BOOGIE_EXE' environment variable can be + set. + + --viper-jar-path + Sets the path to the required Viper binaries ('silicon.jar' or + 'carbon.jar'). Only the binary for the selected backend is + required. You can either use the provided binary packages installed + by default or compile your own from source (see below). + Expects either a single path or a colon- (Unix) or semicolon- + (Windows) separated list of paths. Alternatively, the environment + variables 'SILICONJAR', 'CARBONJAR' or 'VIPERJAR' can be set. + +To see all possible command line options, invoke ``nagini`` without arguments. + + +Alternative Viper Versions +========================== + +To use a more recent or custom version of the Viper infrastructure, follow the +`instructions here `_. Look for +``sbt assembly`` to find instructions for packaging the required JAR files. Use the +parameters mentioned above to instruct Nagini to use your custom Viper version. + + +Troubleshooting +======================= + +1. On Windows: During the setup, you get an error like ``Microsoft Visual C++ 14.0 is required.`` or ``Unable to fnd vcvarsall.bat``: + + Python cannot find the required Visual Studio C++ installation, make sure you have either installed the Build Tools or checked the "Common Tools" option in your regular Visual Studio installation (see above). + +2. While verifying a file, you get a stack trace ending with something like ``No matching overloads found``: + + The version of Viper you're using does not match your version of Nagini. Try updating both to the newest version.