v/README.md

303 lines
9.7 KiB
Markdown
Raw Normal View History

2020-04-19 20:46:18 +02:00
<div align="center">
<p>
<img width="80" src="https://raw.githubusercontent.com/vlang/v-logo/master/dist/v-logo.svg?sanitize=true">
2020-04-13 05:11:56 +02:00
</p>
2020-04-19 20:46:18 +02:00
<h1>The V Programming Language</h1>
2019-06-22 20:22:41 +02:00
2022-05-04 17:06:41 +02:00
[vlang.io](https://vlang.io) | [Docs](https://github.com/vlang/v/blob/master/doc/docs.md) | [Changelog](https://github.com/vlang/v/blob/master/CHANGELOG.md) | [Speed](https://fast.vlang.io/) | [Contributing & compiler design](https://github.com/vlang/v/blob/master/CONTRIBUTING.md)
2020-04-13 05:11:56 +02:00
</div>
<div align="center">
2019-06-22 20:22:41 +02:00
<!--
2020-04-19 20:46:18 +02:00
[![Build Status][WorkflowBadge]][WorkflowUrl]
-->
2022-05-04 17:06:41 +02:00
[![Sponsor][SponsorBadge]][SponsorUrl] [![Patreon][PatreonBadge]][PatreonUrl] [![Discord][DiscordBadge]][DiscordUrl] [![Twitter][TwitterUrl]][TwitterBadge]
2019-06-23 16:13:56 +02:00
2020-04-13 05:11:56 +02:00
</div>
2019-06-22 20:22:41 +02:00
2019-06-24 16:04:19 +02:00
## Key Features of V
2019-08-12 10:00:29 +02:00
- Simplicity: the language can be learned in less than an hour
2021-04-08 02:31:52 +02:00
- Fast compilation: ≈110k loc/s with a Clang backend,
≈1 million loc/s with native and tcc backends *(Intel i5-7500, SSD, no optimization)* ([demo video](https://www.youtube.com/watch?v=pvP6wmcl_Sc))
2019-06-24 16:07:41 +02:00
- Easy to develop: V compiles itself in less than a second
- Performance: as fast as C (V's main backend compiles to human-readable C)
2019-06-28 01:54:42 +02:00
- Safety: no null, no globals, no undefined behavior, immutability by default
2019-06-24 16:04:19 +02:00
- C to V translation
2019-06-24 16:36:30 +02:00
- Hot code reloading
2021-04-08 02:31:52 +02:00
- [Innovative memory management](https://vlang.io/#memory) ([demo video](https://www.youtube.com/watch?v=gmB8ea8uLsM))
2020-01-12 20:30:21 +01:00
- [Cross-platform UI library](https://github.com/vlang/ui)
- Built-in graphics library
- Easy cross-compilation
2019-06-24 16:04:19 +02:00
- REPL
2020-08-11 01:07:17 +02:00
- [Built-in ORM](https://github.com/vlang/v/blob/master/doc/docs.md#orm)
- [Built-in web framework](https://github.com/vlang/v/blob/master/vlib/vweb/README.md)
2019-09-07 13:50:12 +02:00
- C and JavaScript backends
- Great for writing low-level software ([Vinix OS](https://github.com/vlang/vinix))
2019-06-24 16:04:19 +02:00
2020-06-30 20:04:56 +02:00
## Stability guarantee and future changes
Despite being at an early development stage, the V language is relatively stable and has
backwards compatibility guarantee, meaning that the code you write today is guaranteed
to work a month, a year, or five years from now.
There still may be minor syntax changes before the 1.0 release, but they will be handled
automatically via `vfmt`, as has been done in the past.
The V core APIs (primarily the `os` module) will still have minor changes until
2021-04-20 14:46:47 +02:00
they are stabilized in V 1.0. Of course the APIs will grow after that, but without breaking
2020-06-30 20:04:56 +02:00
existing code.
Unlike many other languages, V is not going to be always changing, with new features
2020-08-06 17:23:54 +02:00
being introduced and old features modified. It is always going to be a small and simple
2020-06-30 20:04:56 +02:00
language, very similar to the way it is right now.
## Installing V - from source *(preferred method)*
2019-06-22 20:22:41 +02:00
### Linux, macOS, Windows, *BSD, Solaris, WSL, Android, etc.
2019-06-22 20:22:41 +02:00
Usually installing V is quite simple if you have an environment that already has a
functional `git` installation.
* *(* ***PLEASE NOTE:*** *If you run into any trouble or you have a different operating
system or Linux distribution that doesn't install or work immediately, please see
[Installation Issues](https://github.com/vlang/v/discussions/categories/installation-issues)
and search for your OS and problem. If you can't find your problem, please add it to an
existing discussion if one exists for your OS, or create a new one if a main discussion
doesn't yet exist for your OS.)*
To get started, simply try to execute the following in your terminal/shell:
2019-06-22 20:22:41 +02:00
```bash
git clone https://github.com/vlang/v
2019-06-29 12:58:52 +02:00
cd v
make
# HINT: Using Windows?: run make.bat in the cmd.exe shell
2019-06-25 23:02:25 +02:00
```
That should be it and you should find your V executable at `[path to V repo]/v`.
`[path to V repo]` can be anywhere.
(As in the hint above, on Windows `make` means running `make.bat`, so make sure you use
the `cmd.exe` terminal.)
2019-10-22 08:21:59 +02:00
2020-06-04 16:21:59 +02:00
Now you can try `./v run examples/hello_world.v` (`v.exe` on Windows).
* *Trouble? Please see the note above and link to
[Installation Issues](https://github.com/vlang/v/discussions/categories/installation-issues) for help.*
2021-01-14 04:08:58 +01:00
V is constantly being updated. To update V, simply run:
2019-09-01 21:56:49 +02:00
2020-08-11 01:07:17 +02:00
```bash
2019-09-01 21:56:49 +02:00
v up
```
### C compiler
2021-01-14 04:08:58 +01:00
It's recommended to use Clang, GCC, or Visual Studio.
If you are doing development, you most likely already have one of those installed.
2019-10-05 14:59:34 +02:00
Otherwise, follow these instructions:
- [Installing a C compiler on Linux and macOS](https://github.com/vlang/v/wiki/Installing-a-C-compiler-on-Linux-and-macOS)
2019-09-01 22:15:47 +02:00
- [Installing a C compiler on Windows](https://github.com/vlang/v/wiki/Installing-a-C-compiler-on-Windows)
However, if none is found when running `make` on Linux or Windows,
2021-01-14 04:08:58 +01:00
TCC is downloaded as the default C backend.
It's very lightweight (several MB) so this shouldn't take too long.
2019-09-01 21:56:49 +02:00
### Symlinking
2019-06-23 13:27:43 +02:00
NB: it is *highly recommended*, that you put V on your PATH. That saves
2020-08-16 22:45:03 +02:00
you the effort to type in the full path to your v executable every time.
V provides a convenience `v symlink` command to do that more easily.
On Unix systems, it creates a `/usr/local/bin/v` symlink to your
executable. To do that, run:
2019-06-22 20:22:41 +02:00
2019-10-15 08:03:21 +02:00
```bash
2019-09-11 14:32:40 +02:00
sudo ./v symlink
2019-06-22 20:22:41 +02:00
```
2020-08-06 17:23:54 +02:00
On Windows, start a new shell with administrative privileges, for
example by <kbd>Windows Key</kbd>, then type `cmd.exe`, right-click on its menu
2020-08-06 17:23:54 +02:00
entry, and choose `Run as administrator`. In the new administrative
shell, cd to the path, where you have compiled v.exe, then type:
2020-08-11 01:07:17 +02:00
```bat
2020-05-31 08:02:27 +02:00
.\v.exe symlink
```
2020-08-11 01:07:17 +02:00
2021-01-14 04:08:58 +01:00
That will make V available everywhere, by adding it to your PATH.
2020-08-06 17:23:54 +02:00
Please restart your shell/editor after that, so that it can pick
the new PATH variable.
2020-08-06 17:23:54 +02:00
NB: there is no need to run `v symlink` more than once - v will
continue to be available, even after `v up`, restarts, and so on.
2020-08-06 17:23:54 +02:00
You only need to run it again, if you decide to move the V repo
folder somewhere else.
2019-08-27 03:17:50 +02:00
### Docker
2019-07-23 02:41:55 +02:00
2020-01-12 20:30:21 +01:00
<details><summary>Expand Docker instructions</summary>
2019-07-23 02:41:55 +02:00
```bash
git clone https://github.com/vlang/v
cd v
docker build -t vlang .
docker run --rm -it vlang:latest
```
2019-06-27 22:32:29 +02:00
2020-08-11 01:07:17 +02:00
### Docker with Alpine/musl
2019-11-28 09:46:52 +01:00
```bash
git clone https://github.com/vlang/v
cd v
docker build -t vlang --file=Dockerfile.alpine .
docker run --rm -it vlang:latest
```
2020-01-12 20:30:21 +01:00
2020-08-11 01:07:17 +02:00
</details>
2019-11-28 09:46:52 +01:00
2019-08-12 09:54:35 +02:00
### Testing and running the examples
Make sure V can compile itself:
2019-06-22 20:22:41 +02:00
2020-08-11 01:07:17 +02:00
```bash
2020-07-19 19:08:53 +02:00
v self
2019-08-12 09:54:35 +02:00
```
2019-06-22 20:22:41 +02:00
2019-10-15 08:03:21 +02:00
```bash
2019-06-26 17:58:59 +02:00
$ v
V 0.2.x
Use Ctrl-C or `exit` to exit
2019-06-22 20:22:41 +02:00
>>> println('hello world')
hello world
>>>
```
2019-10-15 08:03:21 +02:00
```bash
2019-08-12 10:00:29 +02:00
cd examples
2019-06-26 18:04:10 +02:00
v hello_world.v && ./hello_world # or simply
v run hello_world.v # this builds the program and runs it right away
2019-06-22 20:22:41 +02:00
2021-04-14 07:51:32 +02:00
v run word_counter/word_counter.v word_counter/cinderella.txt
2019-06-24 17:13:02 +02:00
v run news_fetcher.v
2019-07-22 04:57:55 +02:00
v run tetris/tetris.v
2019-06-22 20:22:41 +02:00
```
2019-06-23 16:16:55 +02:00
<img src='https://raw.githubusercontent.com/vlang/v/master/examples/tetris/screenshot.png' width=300>
NB: In order to build Tetris or 2048 (or anything else using `sokol` or `gg` graphics modules)
on some Linux systems, you need to install `libxi-dev` and `libxcursor-dev` .
## V net.http, net.websocket, `v install`
If you plan to use the net.http module, or the net.websocket module, you also need to install
OpenSSL on non-Windows systems:
2019-06-22 20:22:41 +02:00
2020-08-11 01:07:17 +02:00
```bash
2019-06-26 18:04:10 +02:00
macOS:
2020-08-06 17:23:54 +02:00
brew install openssl
2019-06-25 20:48:34 +02:00
2019-08-09 10:17:56 +02:00
Debian/Ubuntu:
2020-08-06 17:23:54 +02:00
sudo apt install libssl-dev
2019-06-22 20:22:41 +02:00
2019-08-09 10:17:56 +02:00
Arch/Manjaro:
2020-08-06 17:23:54 +02:00
openssl is installed by default
2019-08-09 10:17:56 +02:00
Fedora:
2020-08-06 17:23:54 +02:00
sudo dnf install openssl-devel
2019-06-22 20:22:41 +02:00
```
2019-06-24 18:53:22 +02:00
## V sync
V's `sync` module and channel implementation uses libatomic.
It is most likely already installed on your system, but if not,
you can install it, by doing the following:
```bash
MacOS: already installed
Debian/Ubuntu:
sudo apt install libatomic1
Fedora/CentOS/RH:
sudo dnf install libatomic-static
```
2020-01-12 20:30:21 +01:00
## V UI
<a href="https://github.com/vlang/ui">
2020-01-19 12:40:44 +01:00
<img src='https://raw.githubusercontent.com/vlang/ui/master/examples/screenshot.png' width=712>
2020-01-12 20:30:21 +01:00
</a>
https://github.com/vlang/ui
2019-12-12 18:22:11 +01:00
<!---
2019-09-15 03:10:12 +02:00
## JavaScript backend
[examples/hello_v_js.v](examples/hello_v_js.v):
2019-10-15 08:01:56 +02:00
```v
2019-09-15 03:10:12 +02:00
fn main() {
for i in 0 .. 3 {
println('Hello from V.js')
}
2019-09-15 03:10:12 +02:00
}
```
```bash
v -o hi.js examples/hello_v_js.v && node hi.js
2019-09-15 03:10:12 +02:00
Hello from V.js
Hello from V.js
Hello from V.js
```
2019-12-12 18:22:11 +01:00
-->
## Android graphical apps
With V's `vab` tool, building V UI and graphical apps for Android can become as easy as:
```
./vab /path/to/v/examples/2048
```
[https://github.com/vlang/vab](https://github.com/vlang/vab).
<img src="https://user-images.githubusercontent.com/768942/107622846-c13f3900-6c58-11eb-8a66-55db12979b73.png">
## Developing web applications
Check out the [Building a simple web blog](https://github.com/vlang/v/blob/master/tutorials/building_a_simple_web_blog_with_vweb/README.md)
tutorial and Gitly, a light and fast alternative to GitHub/GitLab:
https://github.com/vlang/gitly
<img src="https://user-images.githubusercontent.com/687996/85933714-b195fe80-b8da-11ea-9ddd-09cadc2103e4.png">
2021-08-16 05:34:13 +02:00
## Vinix, an OS/kernel written in V
V is great for writing low-level software like drivers and kernels.
2021-08-16 07:37:13 +02:00
Vinix is an OS/kernel that already runs bash, GCC, V, and nano.
2021-08-16 05:34:13 +02:00
https://github.com/vlang/vinix
<img src="https://github.com/vlang/vinix/raw/main/screenshot.png?raw=true">
## Troubleshooting
2020-05-22 17:43:39 +02:00
Please see the [Troubleshooting](https://github.com/vlang/v/wiki/Troubleshooting) section on our [wiki page](https://github.com/vlang/v/wiki)
2020-04-19 20:46:18 +02:00
[WorkflowBadge]: https://github.com/vlang/v/workflows/CI/badge.svg
[DiscordBadge]: https://img.shields.io/discord/592103645835821068?label=Discord&logo=discord&logoColor=white
2020-10-25 02:21:36 +02:00
[PatreonBadge]: https://img.shields.io/endpoint.svg?url=https%3A%2F%2Fshieldsio-patreon.vercel.app%2Fapi%3Fusername%3Dvlang%26type%3Dpledges
2020-04-19 20:46:18 +02:00
[SponsorBadge]: https://camo.githubusercontent.com/da8bc40db5ed31e4b12660245535b5db67aa03ce/68747470733a2f2f696d672e736869656c64732e696f2f7374617469632f76313f6c6162656c3d53706f6e736f72266d6573736167653d254532253944254134266c6f676f3d476974487562
[TwitterBadge]: https://twitter.com/v_language
[WorkflowUrl]: https://github.com/vlang/v/commits/master
[DiscordUrl]: https://discord.gg/vlang
[PatreonUrl]: https://patreon.com/vlang
[SponsorUrl]: https://github.com/sponsors/medvednikov
[TwitterUrl]: https://img.shields.io/twitter/follow/v_language.svg?style=flatl&label=Follow&logo=twitter&logoColor=white&color=1da1f2