Skip to content

Commit d7ec888

Browse files
ChemaclassChemaclass
committed
simplify getting started
and create installation doc with nixos #100
1 parent f9a2011 commit d7ec888

File tree

2 files changed

+118
-87
lines changed

2 files changed

+118
-87
lines changed

‎content/documentation/getting-started.md‎

Lines changed: 10 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
+++
22
title = "Getting Started"
3-
weight = 1
3+
weight = 0
44
+++
55

66
## Requirements
@@ -10,107 +10,30 @@ weight = 1
1010

1111
## Quick Start
1212

13-
Scaffold a new project:
13+
Create a fresh project and drop into the REPL:
1414

1515
```bash
1616
composer create-project --stability dev phel-lang/cli-skeleton example-app
1717
cd example-app
1818
composer repl
1919
```
2020

21-
> For web projects: [web-skeleton](https://github.com/phel-lang/web-skeleton)
22-
23-
### Use the standalone PHAR
24-
25-
Prefer to try Phel without installing Composer dependencies? Download the
26-
pre-built [`phel.phar`](https://github.com/phel-lang/phel-lang/releases) from the
27-
latest GitHub release:
28-
29-
```bash
30-
curl -L https://github.com/phel-lang/phel-lang/releases/latest/download/phel.phar -o phel.phar
31-
php phel.phar --version
32-
```
33-
34-
You can execute the same commands as the Composer-installed binary. For example:
35-
36-
```bash
37-
php phel.phar repl
38-
php phel.phar run src/main.phel
39-
php phel.phar test --filter foo
40-
```
41-
42-
## Manual Setup
43-
44-
```bash
45-
mkdir hello-world && cd hello-world
46-
composer init
47-
composer require phel-lang/phel-lang
48-
mkdir src
49-
```
50-
51-
Optional config (`phel-config.php`):
52-
53-
```php
54-
<?php
55-
return (new \Phel\Config\PhelConfig())
56-
->setSrcDirs(['src']);
57-
```
58-
59-
Sample Phel file (`src/main.phel`):
60-
61-
```phel
62-
(ns hello-world\main)
63-
(println "Hello, World!")
64-
```
65-
66-
## Run Code
67-
68-
**From CLI:**
69-
70-
```bash
71-
vendor/bin/phel run src/main.phel
72-
```
73-
74-
**With PHP Server:**
75-
76-
```php
77-
<?php
78-
require __DIR__ . '/../vendor/autoload.php';
79-
\Phel\Phel::run(__DIR__ . '/../', 'hello-world\\main');
80-
```
81-
82-
```bash
83-
php -S localhost:8000 ./src/index.php
84-
```
85-
86-
> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="width: 16px; height: 16px; display: inline-block; vertical-align: middle; margin-right: 4px;"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path></svg> [More on running code](/documentation/cli-commands#run-a-script)
87-
88-
## REPL
89-
90-
```bash
91-
vendor/bin/phel repl
92-
```
93-
94-
Try:
21+
Inside the REPL try:
9522

9623
```phel
9724
(def name "World")
9825
(println "Hello" name)
9926
```
10027

101-
> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="width: 16px; height: 16px; display: inline-block; vertical-align: middle; margin-right: 4px;"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path></svg> [More on REPL](/documentation/repl)
102-
103-
## Testing
28+
Exit the REPL with `Ctrl+D` and run the default script:
10429

10530
```bash
106-
vendor/bin/phel test --filter foo
31+
vendor/bin/phel run src/main.phel
10732
```
10833

109-
> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="width: 16px; height: 16px; display: inline-block; vertical-align: middle; margin-right: 4px;"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path></svg> [More on testing](/documentation/testing)
110-
111-
## Editor Support
34+
## Where to go next
11235

113-
- [PhpStorm](https://github.com/phel-lang/phel-intellij-plugin)
114-
- [VSCode](https://github.com/phel-lang/phel-vs-code-extension)
115-
- [Emacs](https://codeberg.org/mmontone/interactive-lang-tools)
116-
- [Vim](https://github.com/danirod/phel.vim)
36+
- Set up Phel another way? See [Installation](/documentation/installation).
37+
- Dive into the CLI workflow: [CLI Commands](/documentation/cli-commands).
38+
- Explore the REPL deeper: [REPL guide](/documentation/repl).
39+
- Learn the core language features: [Basic Types](/documentation/basic-types).

‎content/documentation/installation.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
+++
2+
title = "Installation"
3+
weight = 1
4+
+++
5+
6+
Phel targets PHP 8.3+, so make sure your environment ships with a compatible PHP
7+
runtime and [Composer](https://getcomposer.org/). Choose the setup that fits
8+
your workflow:
9+
10+
## Composer
11+
12+
For a ready-to-run starter project:
13+
14+
```bash
15+
composer create-project --stability dev phel-lang/cli-skeleton example-app
16+
cd example-app
17+
composer repl
18+
```
19+
20+
Prefer to wire Phel into an existing codebase? Pull it in as a dependency:
21+
22+
```bash
23+
composer require phel-lang/phel-lang
24+
```
25+
26+
Then add a source directory and start writing `*.phel` files. Commands are
27+
available through `vendor/bin/phel`.
28+
29+
## Standalone PHAR
30+
31+
Try Phel without touching `composer.json`. Download the pre-built PHAR from the
32+
[latest GitHub release](https://github.com/phel-lang/phel-lang/releases):
33+
34+
```bash
35+
curl -L https://github.com/phel-lang/phel-lang/releases/latest/download/phel.phar -o phel.phar
36+
php phel.phar --version
37+
```
38+
39+
Use it exactly like the Composer-installed binary:
40+
41+
```bash
42+
php phel.phar repl
43+
php phel.phar run src/main.phel
44+
php phel.phar test --filter foo
45+
```
46+
47+
## NixOS
48+
49+
Phel needs PHP 8.3+ and Composer. On NixOS you can spin up an environment that
50+
provides both tools without polluting your system profile.
51+
52+
### Install from nixpkgs
53+
54+
`phel` is available in [nixpkgs](https://github.com/NixOS/nixpkgs/blob/master/pkgs/by-name/ph/phel/package.nix),
55+
so you can make it part of your system or user environment:
56+
57+
```nix
58+
{ pkgs, ... }: {
59+
environment.systemPackages = with pkgs; [ phel ];
60+
}
61+
```
62+
63+
With [Home Manager](https://nix-community.github.io/home-manager/):
64+
65+
```nix
66+
{ pkgs, ... }: {
67+
home.packages = [
68+
pkgs.phel
69+
];
70+
}
71+
```
72+
73+
To try Phel without persisting it, start an ad-hoc shell:
74+
75+
```bash
76+
nix shell nixpkgs#phel
77+
```
78+
79+
### Ephemeral shell
80+
81+
Run Composer-based workflows inside an ad-hoc shell:
82+
83+
```bash
84+
nix-shell -p php83 php83Packages.composer --run \
85+
"composer create-project --stability dev phel-lang/cli-skeleton example-app"
86+
```
87+
88+
Inside the spawned shell, `cd example-app` and use commands such as
89+
`composer repl` or `vendor/bin/phel`.
90+
91+
### Project shell.nix
92+
93+
For a repeatable development setup, drop this `shell.nix` into your project and
94+
run `nix-shell`:
95+
96+
```nix
97+
{ pkgs ? import <nixpkgs> { } }:
98+
99+
pkgs.mkShell {
100+
packages = with pkgs; [
101+
php83
102+
php83Packages.composer
103+
];
104+
}
105+
```
106+
107+
> Using flakes? Replace the last snippet with a `devShell` definition that pulls
108+
> in the same `php83` and `php83Packages.composer` packages.

0 commit comments

Comments
 (0)