Development environment (original) (raw)

This pages lists one known working setup that the author believes to be pretty much what everyone in the team uses. Hit me (protz) up or edit this page if you have questions / improvements. Some of these points about Git & Windows also apply to F*.

Table of contents

Git, Cygwin, Windows and happiness

Most of us use Cygwin, and hardly ever open a cmd prompt. The git we use is the git package from Cygwin. We use this: https://github.com/protz/ocaml-installer/wiki to get a working Cygwin setup and a working OCaml setup in there. Here are some classic problems you may encounter when using Git on Windows and/or Cygwin after that.

Line endings

Windows uses CRLF. Linux/OSX use LF. Most Windows editors will silently "convert" Unix-style line endings into Windows-style line endings (source: https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration#Formatting-and-Whitespace). There are two philosophical currents that go about solving this problem:

miTLS and F* use the latter. I use a Cygwin editor that never changes line-endings (vim) but some collaborators may use something else; the .gitattributes file prevents them from messing up. If you get:

The file will have its original line endings in your working directory. warning: LF will be replaced by CRLF in Foo.fst

then you edited Foo.fst with an editor that thought it was a good idea to replace all line endings in your file.

Pro tips:

File permissions

In the Cygwin git scenario, I've never had any issues with file permissions. But there have been numerous instances of the dreaded "mode conflict" reported in the wild.

diff --git a/foo b/foo
old mode 100644
new mode 100755

Symptoms are the snippet above showing up in your git diff. (And you can't git revert or git checkout these changes away.) git config core.filemode false seems to fix it. Pro tip: you may want to make this git config --global core.filemode false.

Cygwin is slow as hell

Symptoms:

Solution: pick solution 2 from https://gist.github.com/k-takata/9b8d143f0f3fef5abdab

Submodule hell

You need to merge but there's a disagreement as to which revision the .fstar submodule should have. You can't git add the submodule. Here's some troubleshooting:

Some tips and tricks

Here's what I have in my ~/.gitconfig. Please note:

[user]
  name = Jonathan Protzenko
  email = protz@microsoft.com

[color]
  ui = true

[core]
  excludesfile = ~/.gitignore
  pager = less -+$LESS -RSX
  quotepath = false
  autocrlf = false

[push]
  default = current

[advice]
  detachedHead = false

[help]
  autocorrect = 1

General working tips

Branching and merging

We expect that the version on master will always, at least, pass tls-gen.

Editor

Mostly, Emacs with the customizations described in https://github.com/mitls/mitls-fstar#configuring-emacs-mode; I recommend using the Cygwin package for Emacs; emacs-w32 is a native Windows program packaged within Cygwin; emacs-x11 uses Cygwin's X11 graphical stack. I use the latter, people have been happy with the former.