Vely logo Empower C
install     tutorials     examples     documentation     license     about

11.0.11 released on Jul 25, 2022

Tutorial-hello world



DESCRIPTION:



Introduction to Vely


Vely is a framework for rapid application design and development.

A Vely application is made of a number of files with ".v" extension. Vely language_statements do something useful for you, and are embedded in C code - the idea is that C code provide basic programming infrastructure and access to libraries. Everything else you do with Vely statements. vv utility will turn those statements into C code, and then compile and link it. So you get a native executable without interpreters, byte-codes and such, which generally means better performance and lighter footprint.

Vely has an automatic garbage collection for all of it, so that helps with memory issues. It also reduces chances of long-running processes leaking memory and eventually crashing.

Your application works by processing requests and sending back replies. A request is via either GET or POST HTTP method. For more, see how Vely works and read more about Vely architecture.

What you'll learn


You'll learn how to:

Prerequisites


First of all, install Vely. Currently Vely is not in distro repos, so the installation will import the signing key (all Vely packages are signed) and repo information, and then you can use standard packaging tools such as apt, dnf, zypper or pacman. The installation page has lots of choices as Linux distros, but if yours is not there, chances are it's a derivative of one of the listed ones. For example, Linuxmint or Deepin are derivatives of Ubuntu, so you'd use a Ubuntu package, while Rocky is a derivative of RedHat, so you'd use RedHat package, Manjaro comes from Archlinux and so on.

Next, to run this as a web application, you must install Apache; you don't need it if you are interested in command_line application only.

It is a good idea to create a separate source code directory for each application (and you can name it whatever you like):
mkdir helloworld
cd helloworld


Hello World


Open a new file called hello.v:
vi hello.v

Copy the following and save the file:
#include "vely.h"

void hello()
{
   out-header default
   @Hello World!
}

The file name ("hello.v") must match the function name implemented in it, so the function's signature is "void hello()". This is because it implements any URL with the request name of "hello". In practicality, it means a URL like:
http://your-web-site/hello?req=hello

The "req" field is a request name and it must be always specified, except when there is only one in the application. That's the case here, so it's unnecessary:
http://your-web-site/hello

When executing from command line, the request name and any other URL fields are passed along via environment variables. More about that in a bit. You can still use any command-line arguments (just like any other program) and get them via get-req statement.

Note the "@" used to do the output, it's the output_statement. You'll probably use that one a lot.

In this case there's only one request file. In a real world application, there'd likely be quite a few. Vely will pick up all .v files and automatically make them into an application. While at it, it will generate a simple request dispatcher that routes incoming request to the appropriate code; in this case a "hello" request will be routed to your "void hello()" function.

Build it


To run any Vely application, you need to create it first. This application will be named "helloworld", but you can name it anything. Do this:
sudo vf -i -u $(whoami) helloworld

This will create a new application home (which is "/var/lib/vv/helloworld"; each Vely app has a home under "/var/lib/vv") and do the application setup for you. Mostly that means create various subdirectories in the home folder, and assign them privileges. In this case only current user (or the result of "whoami" Linux command) will own those directories with 0700 privileges; it means a secure setup.

Next, build your application; use vv command line utility for that:
vv -q helloworld

What you're doing here is making your application (-q option), and specifying that your application name is "helloworld".

Run as a web application


Vely uses FastCGI protocol to run your application. With FastCGI, your application runs as server (daemon) processes that do not exit; they stay up and process incoming requests. Each process does so one request at a time; however multiple processes do so truly in parallel. Linux processes are super-lightweight and this works quite well performance wise. And as a result, all the programming is single-threaded, making it simpler.

Vely will produce two executables: one for a web application and one for command line execution. Web application executable is located at:
/var/lib/vv/bld/helloworld/helloworld.fcgi

Before you can use your application, you must start it as FastCGI server processes. To start Hello World app:
vf helloworld

vf is a FastCGI process manager. You can use it to run any FastCGI program, not just Vely applications. By default, it will only run a super small daemon (typically around 100KB of memory), and will only start the actual application processes when they are needed, however once running, each process will stay up for a while, and only eventually and gradually go away if unused. This makes for good peak performance and very low memory usage. You can also start a fixed number of processes, such as:
vf -w 10 helloworld

Here, 10 processes are started and will stay running, which provides steady response time througout. Vely processes are generally very light in terms of memory usage, so that's a good option too. vf has a number of options to help you achieve best performance.

You can see the response from your web application right away from command line (see more about FastCGI_client):
export REQUEST_METHOD=GET
export QUERY_STRING="req=hello"
cgi-fcgi -connect /var/lib/vv/helloworld/sock/sock  /


Run from web browser


Next, you need to setup a web server. In this case you'll use Apache, but it can be any web server with FastCGI support, and all major ones support it (if you're having trouble with this, see apache_reverse_proxy). For Debian systems (like Ubuntu), enable proxy and proxy_fcgi modules:
sudo a2enmod proxy
sudo a2enmod proxy_fcgi

Then, open your Apache configuration file in editor, for Debian systems:
sudo vi /etc/apache2/apache2.conf

and for Fedora systems (like Red Hat) and Arch Linux:
sudo vi /etc/httpd/conf/httpd.conf

Add this to the end of file:
ProxyPass "/helloworld" unix:///var/lib/vv/helloworld/sock/sock|fcgi://localhost/helloworld

This will create a Unix domain socket between the web server and your Vely application. This allows web server to serve responses from your application really, really fast.

Note that you can also use TCP sockets for the same purpose; they are probably more appropriate if your application runs on a different computer than the server. Note that in such case the two computers must be on a secure network, since the TCP communication is not encrypted. Generally, that's not an issue, since for other reasons (such as performance and reliability), you wouldn't want your application server to be on the open Internet anyway. You may also use TCP in some other situations, such as if you containerize_application.

Save the file and restart Apache, for Debian systems (like Ubuntu):
sudo systemctl restart apache2

or for Fedora systems (like RedHat) and Arch Linux:
sudo systemctl restart httpd

Now go ahead and try helloworld app:
http://127.0.0.1/helloworld

Note: if you're not using localhost (i.e. 127.0.0.1), port 80 may be blocked and you may need to open it via firewall. Use "firewall-cmd" (for Fedora based systems) or "ufw" (for Debian systems) to open access to port 80.

The result:
Vely

You can also run it with curl:
curl -s "http://127.0.0.1/helloworld"

The result:
Vely


Run in the command line


Every Vely application can run as Command Line Interface (CLI), i.e. in the command-line. The command line executable will be at /var/lib/vv/bld/helloworld/helloworld.  Note that you can use this as a CGI program as well, if you wish to do so.

Command-line program works just like the web application, and produces the same output. It also takes the same input, so you need to set a few environment variables, namely REQUEST_METHOD and QUERY_STRING among others.

So, to run your application in command line, set the variables and just run the executable:
export REQUEST_METHOD=GET
export QUERY_STRING=""
/var/lib/vv/bld/helloworld/helloworld

The result:
Vely

Since our simple Hello World program is made of only a single request, there is no need to specify a "req" URL field in QUERY_STRING.

Now, as you can see, HTTP headers are output, just as they are for the web application. Generally, for a pure command line program, you don't want any headers. To suppress them add VV_SILENT_HEADER:
export REQUEST_METHOD=GET
export QUERY_STRING=""
export VV_SILENT_HEADER=yes
/var/lib/vv/bld/helloworld/helloworld

The result:
Vely


Changing your code


When you change your source code and recompile, vf will automatically pick up that the executable has changed and reload (see vf if you wish to change this behavior), making your web application live instantly. For example, change hello.v to this:
#include "vely.h"

void hello()
{
   out-header default
   @Hello World! And a good day to you too!
}

and then recompile:
vv -q helloworld

Now try again:
http://127.0.0.1/helloworld

The result:
Vely


Generated C code, errors, tracing and debugging


Generated C code is located at:
/var/lib/vv/bld/helloworld/__hello.o.c

It's useful if you'd like to see it or debug your code.

If you are using your Vely application as a command line program, you can debug it simply by using gdb.

Note that in order to see the debugging symbols (such as variable names), you should compile your application with --debug flag:
vv -q --debug helloworld

For FastCGI processes, you'd want to start your application as a single process, generally as few as possible. First, find out the PID of your process:
ps -ef|grep helloworld.fcgi

Then you can load gdb with your application and attach to it - assuming the PID is 12345:
sudo gdb /var/lib/vv/bld/helloworld/helloworld.fcgi
... att 12345

To break in your code (in this case in function hello()), do this in gdb:
br hello

If you'd like to break in Vely's request dispatcher, i.e. just before any request is handled:
br vely_dispatch_request

From then on, you can set breakpoints, continue, stop and do anything else to debug your program.

When you debug Vely application in gdb, each Vely statement is a single execution unit. This is very useful when reporting errors, since they are reported referencing lines in .v file, in this case hello.v. Sometimes you'd want to use line numbers of the generated C file, in which case you'd compile with --c-lines flag:
vv -q --c-lines helloworld

Another way to debug your application is to use tracing (see trace). To enable tracing, compile your application with --trace flag:
vv -q --debug --trace helloworld

Trace files are in the trace directory, see how_vely_works. In our case, trace file would be in this directory:
/var/lib/vv/helloworld/app/trace

and trace file name for the process you're debugging would be (with timestamp being of the time it's written):
trace-12345-2022-05-17-22-46-54

In addition to this, learn more about debugging Vely applications.

Want to learn more about Vely?


Check out documentation at vely.dev, along with downloads and examples. Or, use man pages installed with Vely.

SEE ALSO:


Tutorials ( tutorials   tutorial-hello_world   tutorial-stock_app   tutorial-file_manager   tutorial-utility  )  SEE ALL (documentation)



Copyright (c) 2022 DaSoftver LLC. Vely is a trademark of Dasoftver LLC. The software and information herein are provided "AS IS" and without any warranties or guarantees of any kind. This web page is licensed under CC-BY-SA-4.0.