Skip to content

Instantly share code, notes, and snippets.

@McTano

McTano/NotesOnREADME.md

Last active August 25, 2020 18:14
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save McTano/5b6c22a21f2ca08891b7f6ba8123563a to your computer and use it in GitHub Desktop.
Save McTano/5b6c22a21f2ca08891b7f6ba8123563a to your computer and use it in GitHub Desktop.
Download ZIP
Raw
NotesOnREADME.md

Notes on the README

  • The sections should be organized in terms of getting the server running instead of as technical steps. i.e. "How to Run the Server". The steps for that should go at the top, because that's what most devs will want to do.

  • Currently the commands for actually running the server are under "Get a GHC Based Development Shell", right?

  • I don't think we need the instructions on how to do each thing manually in each section. If someone wants to know how it's done, they can look at the Makefile. Or if the steps aren't the same as what the makefile does, maybe we could put these in another file to keep the README simpler.

  • Why do we need two different dev shells? Is that because we can't have the dependencies for both the client and the server at the same time. What is actually made available in each? Just the compilers? This could be explained more.

  • We should rename the make commands in terms of what we're building instead of the compiler used. build-client and build-server were better than build-ghcjs and build-ghc.

  • Can we put those nix-build commands under aliases in the Makefile, so devs don't have to pass the args each time?

  • You mentioned you could have make run check if it's in nix-shell and go in if not. I think it would be great if we could do something like that wherever a command needs to be run in the nix-shell. If we could do that, we might not need the developer to run nix-shell directly at all.

  • What is the difference between running the nix-build commands at the beginning vs. running the make commands inside the nix-shell? What is the recommended way to build the server and the front-end?

Carnap has a GHCJS (client side) and a GHC (server side) part.

  • I think this could be made clearer. We don't actually refer to the Carnap code as a "client" here, but we do elsewhere. I think referring to them by the compilers muddies the waters. Talking about 's a bit misleading, because the javascript code isn't really a client. It's more of a library.

  • Come to think of it, I'm a bit confused about what the relationship between the Carnap-Client and Carnap-GHCJS folders are.

  • Maybe its clearer to talk the client-side library as the Javascript part, instead of mentioning GHCJS.

To perform the process manually, first make sure to copy Carnap-Server/config/settings-example.yml to Carnap-Server/config/settings.yml, and to create a data directory (in the below, called dataroot). Then run:

  • This should give the actual commands in the snippet so devs can copy-paste, if we keep the manual steps.

  • I'm getting this error after running the nix-build command to build the client, when the client-out directory already exists. I assume this could be avoided with a flag.

error: cannot create symlink '/home/tano/code/Carnap/client-out'; already exists

EDIT: Now I'm not getting it. Maybe it's been fixed on another branch already.

Sections

How to Build And Run the Server

Prerequisites

Set up Cachix

Make commmands

How to compile just the client-side javascript code

Explanation of dev shells

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment