Vely logo install
examples
documentation

Vely 15.2.0 released on Jan 18, 2023
Articles updated Jan 17, 2023

Example: hello world



Description:


This is a simple Hello World example. It explains basics of making applications as well as tracing and debugging them.

In a nutshell: 2 source files, 7 lines of code; no database; command line; web browser; Nginx; Unix sockets;

Screenshots of application


Hello World output:

Vely


Setup prerequisites


Install Vely - you can use standard packaging tools such as apt, dnf, pacman or zypper.

Because it is used in this example, you will need to install Nginx as a web server.

After installing Vely, turn on syntax highlighting in vim if you're using it:

vv -m


Get the source code


The source code is a part of Vely installation. It is a good idea to create a separate source code directory for each application (and you can name it whatever you like). In this case, unpacking the source code will do that for you:

tar xvf $(vv -o)/examples/hello_world.tar.gz
cd hello_world


Setup application


The very first step is to create an application. The application will be named "hello_world", but you can name it anything (if you do that, change it everywhere). It's simple to do with vf:

sudo vf -i -u $(whoami) hello_world

This will create a new application home (which is "/var/lib/vv/hello_world") 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.

Build application


Use vv utility to make the application:

vv -q


Start your application server


To start the application server for your web application use vf FastCGI process manager. The application server will use a Unix socket to communicate with the web server (i.e. a reverse-proxy):

vf -w 3 hello_world

This will start 3 daemon processes to serve the incoming requests. You can also start an adaptive server that will increase the number of processes to serve more requests, and gradually reduce the number of processes when they're not needed:

vf hello_world

See vf for more options to help you achieve best performance.

To stop your application server:

vf -m quit hello_world


Setup web server


This shows how to connect your application listening on a Unix socket (started with vf) to Nginx web server.

- Step 1:
You will need to edit the Nginx configuration file. For Ubuntu and similar:

sudo vi /etc/nginx/sites-enabled/default

while on Fedora and other systems it might be at:

sudo vi /etc/nginx/nginx.conf


Add the following in the "server {}" section ("/hello_world" is the application path (see request_URL) and "hello_world" is your application name):

location /hello_world { include /etc/nginx/fastcgi_params; fastcgi_pass  unix:///var/lib/vv/hello_world/sock/sock; }

- Step 2:
Finally, restart Nginx:

sudo systemctl restart nginx


Access application server from the browser


Use the following URL(s) to access your application server from a web client like browser (see request_URL). Use actual IP or web address instead of 127.0.0.1 if different.

#Hello world 
http://127.0.0.1/hello_world/hello

Note: if your server is on the Internet and it has a firewall, you may need to allow HTTP traffic - see ufw, firewall-cmd etc.

Access application server from command line


To access your application server from command line (instead through web browser/web server), use "cgi-fcgi" to see the application response:

#Hello world 
export REQUEST_METHOD=GET
export SCRIPT_NAME='/hello_world'
export PATH_INFO='/hello'
export QUERY_STRING=''
cgi-fcgi -connect /var/lib/vv/hello_world/sock/sock /

Note: to suppress output of HTTP headers, add this before running "cgi-fcgi":

export VV_SILENT_HEADER=yes

If you need to, you can also run your application as a CGI program.

Run program from command line


Execute the following to run your application from command line (as a command-line utility):

#Hello world 
export REQUEST_METHOD=GET
export SCRIPT_NAME='/hello_world'
export PATH_INFO='/hello'
export QUERY_STRING=''
/var/lib/vv/bld/hello_world/hello_world

Note: to suppress output of HTTP headers, add this before running /var/lib/vv/bld/hello_world/hello_world program:

export VV_SILENT_HEADER=yes

Note: if running your program as a command-line utility is all you want, you don't need to run an application server.

Files:


You are now done with the example! What follows are the source files in this project so you can examine how it works:

Hello World (hello.vely)


Hello World example outputs HTTP header and a simple message back to the browser.

The file name ("hello.vely") must match the function name implemented in it, so the function's signature is "void hello()". Call it with a URL like:

http://your-web-site/hello_world/hello

Note "/hello_world" path segment - that's the application path and by default the same as application name (see how_vely_works and request_URL). The following path segment is "/hello", which is the request name, and it must match the function name that implements it.

Note the "@" is 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 .vely files and automatically make them into an application. While at it, it will generate a simple request dispatcher that routes an incoming request to the appropriate code; in this case a "hello" request will be routed to your "void hello()" function.

#include "vely.h"

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


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.vely to this:

#include "vely.h"

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

and then recompile:

vv -q

Now try again from the browser:

http://127.0.0.1/hello_world/hello

The result:

Vely


Generated C code, errors, tracing and debugging


Generated C code is located at:

/var/lib/vv/bld/hello_world/__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

For FastCGI processes, you'd want to start your application as a single process, generally as few as possible, for example, stop your application first and then start as a single process:

vf -m quit hello_world
vf -w 1 hello_world

First, find out the PID of your process:

ps -ef|grep hello_world.fcgi

Then you can load gdb with your application and attach to it - assuming the PID is 12345:

sudo gdb /var/lib/vv/bld/hello_world/hello_world.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 applications in gdb, each Vely statement is a single execution unit. This is very useful when reporting errors, since they are reported referencing lines in .vely file, in this case hello.vely. 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

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

vv -q --debug --trace

Trace files are in the trace directory, see how_vely_works. In our case, trace file would be in this directory:

/var/lib/vv/hello_world/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.

See also:


Examples ( example_cookies   example_create_table   example_docker   example_file_manager   example_form   example_hello_world   example_json   example_multitenant_SaaS   examples   example_sendmail   example_shopping   example_stock   example_utility   example_write_report  )  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. Vely elephant logo (c) 2022 DaSoftver LLC. This web page is licensed under CC-BY-SA-4.0.