Skip to content

A peer-to-peer stack for code collaboration

Sundry small improvements to onboarding experience. (#189)

Julian Arni9ca17c44fa07
diff --git a/README.md b/README.md
index 9ac8b98..5fa5e39 100644
--- a/README.md
+++ b/README.md
@@ -5,15 +5,18 @@ seminal Root.
> - Vallemont, *Curiosities of nature and art in husbandry and gardening* (1707)
A LISP in the spirit of [Black](http://pllab.is.ocha.ac.jp/~asai/Black/) and
-other colors.
+other colors. Easily define and interact with shared and upgradable state
+machines.
## Installation
-Install stack. Then:
+Install [stack](https://docs.haskellstack.org/en/stable/install_and_upgrade/). Then:
```
stack build
```
+(You'll need libpq-dev/postgresql to build the server. See [GettingStarted](https://radicle.readthedocs.io/en/latest/guide/GettingStarted.html) for more info.
+
## How to run tests
```
@@ -29,13 +32,11 @@ You should probably run the client against radicle.xyz for fuller
functionality.
```
-stack exec radicle-client -- --config rad/repl.rad --url radicle.xyz
+stack exec radicle-client -- --config rad/repl.rad
```
-## The language
+## More
-The language currently lacking good documentation. A good place to get a sense
-for it is in the rad/ directory, which contains a number of radicle files.
+Radicle has a [webpage](radicle.xyz), and a [guide](docs.radicle.xyz) which
+contain a lot more information on `radicle`.
-Variables defined there are usually documented. This means you can type `(doc
-'ident)` to retrieve documentation for the identifier `ident`.
diff --git a/cloudbuild.yaml b/cloudbuild.yaml
index fa3cbd9..68b24a1 100644
--- a/cloudbuild.yaml
+++ b/cloudbuild.yaml
@@ -48,7 +48,7 @@ steps:
args:
- '-c'
- |
- stack exec ref-doc
+ stack exec radicle-ref-doc
- id: "Save cache"
name: gcr.io/cloud-builders/gsutil
diff --git a/docs/source/guide/GettingStarted.rst b/docs/source/guide/GettingStarted.rst
index c5a6910..c63f2b0 100644
--- a/docs/source/guide/GettingStarted.rst
+++ b/docs/source/guide/GettingStarted.rst
@@ -20,6 +20,9 @@ In order to build from source, you'll need stack_:
curl -sSL https://get.haskellstack.org/ | sh
+The centralized server also requires PostgreSQL libs. On Ubuntu, you can
+`apt-get install libpq-dev`. On MacOS, you can `brew install postgresql'.
+
You can then download and build the latest source code for `radicle` from
http://git.oscoin.io/radicle:
diff --git a/exe/Server/API.hs b/exe/API.hs
similarity index 100%
rename from exe/Server/API.hs
rename to exe/API.hs
diff --git a/exe/Doc.hs b/exe/Doc.hs
index ee99a7b..50d336c 100644
--- a/exe/Doc.hs
+++ b/exe/Doc.hs
@@ -1,6 +1,6 @@
-- | This executable processes literate radicle files. It accepts Markdown, and
-- runs the code inside code blocks (within three backticks).
-module Doc where
+module Doc (main) where
import Protolude
diff --git a/exe/Server/Client.hs b/exe/RadicleExe.hs
similarity index 75%
rename from exe/Server/Client.hs
rename to exe/RadicleExe.hs
index 98150ee..f286bcd 100644
--- a/exe/Server/Client.hs
+++ b/exe/RadicleExe.hs
@@ -1,6 +1,6 @@
{-# LANGUAGE QuasiQuotes #-}
-module Client where
+module RadicleExe (main) where
import API
import Control.Monad.Catch (MonadThrow)
@@ -10,10 +10,12 @@ import GHC.Exts (fromList)
import Network.HTTP.Client (defaultManagerSettings, newManager)
import qualified Network.HTTP.Client as HttpClient
import Options.Applicative
+import Prelude (String)
import Protolude hiding (TypeError, option)
import Radicle
import Servant.Client
import System.Console.Haskeline (InputT)
+import System.Directory (doesFileExist)
import Radicle.Internal.Doc (md)
import qualified Radicle.Internal.PrimFns as PrimFns
@@ -24,7 +26,11 @@ main = do
cfgFile <- case configFile opts' of
Nothing -> getConfigFile
Just cfg -> pure cfg
- cfgSrc <- readFile cfgFile
+ cfgSrc <- do
+ exists <- doesFileExist cfgFile
+ if exists
+ then readFile cfgFile
+ else die $ "Could not find file: " <> toS cfgFile
hist <- case histFile opts' of
Nothing -> getHistoryFile
Just h -> pure h
@@ -33,10 +39,18 @@ main = do
where
allOpts = info (opts <**> helper)
( fullDesc
- <> progDesc "Run the radicle REPL"
- <> header "rad - The radicle REPL"
+ <> progDesc radDesc
+ <> header "The radicle intepreter"
)
+radDesc :: String
+radDesc
+ = "Interprets a radicle program.\n"
+ <> "\n"
+ <> "This program can also be used as a REPL by providing a file "
+ <> "that defines a REPL. An example is the rad/repl.rad file included "
+ <> "in the distribution."
+
-- * CLI Opts
data Opts = Opts
@@ -46,15 +60,25 @@ data Opts = Opts
opts :: Parser Opts
opts = Opts
- <$> optional (strOption
- ( long "config"
- <> metavar "FILE"
- <> help "rad configuration file"
- ))
+ <$> argument (optional str)
+ ( metavar "FILE"
+ <> help
+ ( "File to interpret."
+ <> "Defaults to $DIR/radicle/config.rad "
+ <> "where $DIR is $XDG_CONFIG_HOME (%APPDATA% on Windows "
+ <> "if that is set, or else ~/.config."
+ )
+ )
<*> optional (strOption
( long "histfile"
+ <> short 'H'
<> metavar "FILE"
- <> help "repl history file"
+ <> help
+ ( "File used to store the REPL history."
+ <> "Defaults to $DIR/radicle/config.rad "
+ <> "where $DIR is $XDG_DATA_HOME (%APPDATA% on Windows "
+ <> "if that is set, or else ~/.local/share."
+ )
))
-- * Primops
@@ -98,11 +122,6 @@ clientPrimFns mgr = fromList . PrimFns.allDocs $ [sendPrimop, receivePrimop]
xs -> throwErrorHere $ WrongNumberOfArgs "receive!" 2 (length xs)
)
--- * Helpers
-
-identV :: Text -> Value
-identV = Keyword . unsafeToIdent
-
-- * Client functions
submit :: Value -> ClientM ()
diff --git a/exe/ReferenceDoc.hs b/exe/ReferenceDoc.hs
index 24a7f7a..e4c2681 100644
--- a/exe/ReferenceDoc.hs
+++ b/exe/ReferenceDoc.hs
@@ -2,7 +2,7 @@
-- | This executable generates the radicle reference docs. This is a markdown
-- document which contains documentation for all the primitive functions and all
-- the functions defined in the prelude.
-module ReferenceDoc where
+module ReferenceDoc (main) where
import Protolude
diff --git a/exe/Repl/Main.hs b/exe/Repl/Main.hs
deleted file mode 100644
index 053a6af..0000000
--- a/exe/Repl/Main.hs
+++ /dev/null
@@ -1,42 +0,0 @@
-module Main (main) where
-
-import Options.Applicative
-import Protolude
-
-import Radicle
-
-main :: IO ()
-main = do
- opts' <- execParser allOpts
- cfgFile <- case configFile opts' of
- Nothing -> getConfigFile
- Just cfg -> pure cfg
- cfgSrc <- readFile cfgFile
- hist <- case histFile opts' of
- Nothing -> getHistoryFile
- Just h -> pure h
- repl (Just hist) (toS cfgFile) cfgSrc replBindings
- where
- allOpts = info (opts <**> helper)
- ( fullDesc
- <> progDesc "Run the radicle REPL"
- <> header "rad - The radicle REPL"
- )
-
-data Opts = Opts
- { configFile :: Maybe FilePath
- , histFile :: Maybe FilePath
- }
-
-opts :: Parser Opts
-opts = Opts
- <$> optional (strOption
- ( long "config"
- <> metavar "FILE"
- <> help "rad configuration file"
- ))
- <*> optional (strOption
- ( long "histfile"
- <> metavar "FILE"
- <> help "repl history file"
- ))
diff --git a/exe/Server/Server.hs b/exe/Server.hs
similarity index 99%
rename from exe/Server/Server.hs
rename to exe/Server.hs
index dac82da..f2977f0 100644
--- a/exe/Server/Server.hs
+++ b/exe/Server.hs
@@ -1,6 +1,6 @@
-- | This file defines a server that can be used as a *centralized* remote for
-- chains.
-module Server where
+module Server (main) where
import Protolude hiding (fromStrict, option)
@@ -48,8 +48,8 @@ import Servant
)
import API
-import DB
import Radicle
+import Server.DB
-- * Types
diff --git a/exe/Server/DB.hs b/exe/Server/DB.hs
index a659766..3062f69 100644
--- a/exe/Server/DB.hs
+++ b/exe/Server/DB.hs
@@ -1,5 +1,5 @@
{-# OPTIONS_GHC -fno-warn-orphans #-}
-module DB where
+module Server.DB where
import Data.List (groupBy, head)
import Database.PostgreSQL.Simple
diff --git a/nix/shell.nix b/nix/shell.nix
index 46a8a0c..92e1bf3 100644
--- a/nix/shell.nix
+++ b/nix/shell.nix
@@ -26,6 +26,6 @@ stdenv.mkDerivation {
alias sbc="stack build --fast --system-ghc --nix-packages zlib radicle:exe:radicle-client"
alias st="stack test --fast --system-ghc --nix-packages zlib"
alias server="stack exec radicle-server -- "
- alias client="stack exec radicle-client -- --config rad/repl.rad"
+ alias client="stack exec radicle -- rad/repl.rad"
'';
}
diff --git a/package.yaml b/package.yaml
index bf1e5a4..9c41495 100644
--- a/package.yaml
+++ b/package.yaml
@@ -79,20 +79,27 @@ tests:
executables:
radicle:
- main: Main.hs
- source-dirs: exe/Repl
- when:
- - condition: impl(ghcjs)
- buildable: false
+ main: RadicleExe.hs
+ source-dirs: exe
+ other-modules: API
dependencies:
- radicle
+ - exceptions
- optparse-applicative
- ghc-options: -threaded -O3
+ - bytestring
+ - servant
+ - http-media
+ - http-client
+ - servant-client
+ when:
+ - condition: impl(ghcjs)
+ buildable: false
+ ghc-options: -main-is RadicleExe -O3 -threaded
radicle-server:
main: Server.hs
- source-dirs: exe/Server
- other-modules: [API, DB]
+ source-dirs: exe
+ other-modules: [API, Server.DB]
when:
- condition: impl(ghcjs)
buildable: false
@@ -108,24 +115,6 @@ executables:
- wai-cors
ghc-options: -main-is Server -O3 -threaded
- radicle-client:
- main: Client.hs
- source-dirs: exe/Server
- other-modules: API
- dependencies:
- - radicle
- - exceptions
- - optparse-applicative
- - bytestring
- - servant
- - http-media
- - http-client
- - servant-client
- when:
- - condition: impl(ghcjs)
- buildable: false
- ghc-options: -main-is Client -O3 -threaded
-
radicle-client-ghcjs:
main: GHCJS.hs
source-dirs: exe/Server
@@ -146,7 +135,7 @@ executables:
buildable: false
ghc-options: -main-is GHCJS -threaded
- doc:
+ radicle-doc:
main: Doc.hs
source-dirs: exe/
other-modules: []
@@ -159,7 +148,7 @@ executables:
- pandoc
ghc-options: -main-is Doc
- ref-doc:
+ radicle-ref-doc:
main: ReferenceDoc.hs
source-dirs: exe/
other-modules: []