Vely logo install | documentation | examples | articles | changelog
16.6.0 released on Mar 08, 2023 | articles updated on Mar 20, 2023

How vely works


Creating an application

A Vely application <app name> is created by an application owner, i.e. an Operating System user who will own its processes and data, by using vf, such as:
sudo vf -i -u $(whoami) <app name>
This will create directory structure described here. Vely application can be used as a FastCGI server, a command_line program or a CGI program. Note that vf is the only Vely utility requiring sudo privileges, and only for application creation.

If you will build an application from source code, the above vf command must run in the directory that contains the application source code. Each application must be in its own separate directory which contains all of its source code.

How Vely works

In a single step, Vely code (.vely files) is precompiled entirely into C, linked, and ready to run as a command-line program or as an application server, or both. Error reporting is based on Vely source code (.vely files), though you can specify generated code lines to be used.

vv will preprocess .vely source files and generate C code for supported statement_APIs (database, file, strings etc.). Then, vv builds both a command-line program and a FastCGI application server executable for application <app name> (the name <app name> is specified when running vf with "-i" flag to create the application). Executables created are located in directory:
/var/lib/vv/bld/<app name>
A FastCGI application runs as a daemon, i.e. it runs in the background and does not exit, serving incoming requests. Typically, a number of FastCGI processes are started to serve incoming processes in parallel; in adaptive mode, the number of processes running may vary according to the load - including zero running processes for near-zero memory usage.

A command-line program works exactly the same way as a FastCGI application; it takes the same input and produces the same output.

.vely files and requests

Files with the .vely extension are Vely source files. You must have at least one Vely source file (.vely file). If a Vely source file starts with an underscore, it is a non_request file, which can implement anything; otherwise it is a request file. A request file implements a request handler, which handles a request_URL sent by the client (such as reverse proxies like Apache or Nginx) or provided to command_line program via environment variables.

Requests and request handlers

To specify the request handler, specify its name in the URL after the application path (see request_URL). A request handler must implement a function named after the base name of .vely file. For example, in a URL such as:
/stocks/add-stock?ticker=ABC&price=130
the application path is "/stocks" (by default it's the application name) and the request name is "add_stock" (hyphens are converted to underscore by Vely). The request name handler must be implemented as function
void add_stock() {...}
in file add_stock.vely.

This correlation between requests and file names makes it easy to find the code you want and to maintain it. Vely will generate the code that will automatically route input requests to the appropriate code based on the request name, so in the above example Vely will automatically invoke function add_stock() implemented in file "add_stock.vely" with input parameters "ticker" and "price" (and their values) available via input-param statement:
void add_stock() {
    input-param ticker
    input-param price
    ...
}

Non-request source code

Not every source code file was meant to handle a request. You might have a number of non_request files that implement other code, such as commonly used functions. Such files are non-request source code and their names must start with underscore ("_").

For example, file "_display_table.vely" might implement a common HTML table displaying code, which is used in various request handlers.

Some non-request source files have predefined meaning: "_startup.vely" (startup_handler), "_before.vely" (before_request_handler) and "_after.vely" (after_request_handler).

Building an application, Makefile

Vely builds an application by looking at .vely and .h files present in the current directory. Therefore you don't have to write a Makefile.

You don't have to specify what source code your application uses - all .vely files will be automatically picked up and compiled, and request handlers (.vely files that don't start with an underscore) are used to generate vely_dispatch_request.vely file (a request-dispatcher). Thus, it is easy to view at a glance what kind of requests an application serves and what is its general purpose. Files with .h extension are standard C include files and are automatically included.

You can see the default implementations for all auto-generated files in directory
/var/lib/vv/bld/<app name>
An example of building a Vely application is:
vv -q --db=mariadb:notes
"-q" options is the most important one - it specifies that you intend to build. In this instance, MariaDB database (named "notes") is used.

Vely builds an application using standard Linux "make" mechanism. Note that when you change the command line options (see vv) in a build statement like above, it has the effect of "make clean", recompiling source files.

Directories and files

While you can keep and compile Vely source files in any directory, the directories used by Vely are always under /var/lib/vv directory. A Vely application is always owned by a single Operating System user, while different applications can be owned by different users. This is the directory structure:
While Vely directories are fixed, you can effectively change their location by creating a soft link. This way, your directories and files can be elsewhere, even on a different disk. For example, to house your files on a different disk:
ln -s /home/disk0/file /var/lib/vv/<app name>/app/file

Memory allocation

Vely uses its own memory allocator based on standard Linux malloc family of functions. It is used internally and for allocating the results of any statements (each statement's documentation specifies which results, if any, are such). The memory will be automatically freed upon the completion of the request - you can also explicitly free them if you need to. This approach avoids costly errors, crashes and memory leaks. See memory_handling.

Data types

Vely statement_APIs use mostly strings (char* type) and numbers ("num" type, which is "long long" for maximum range of uses, "num32" for a 32-bit integer, "dbl" for a double precision number), "bool" (with true and false value as provided by stdbool.h) and other data types as specified. When a "number" is specified anywhere without an additional qualification, it is assumed to be of "num" type. If a type is not specified, it is either a string or a number, depending on the context in which it is used - in those cases the type is not specified for simplicity.

Names of objects

Do not use object names (such as variables, functions, types) that start with "_vv", "_vely", "vv" or "vely" as those are reserved by Vely.

See also

General ( deploying_application   how_vely_works   quality_control   rename_files   SELinux   vely   vely_architecture   vely_removal   vf   vv   why_Vely  )  SEE ALL (documentation)


Copyright (c) 2017-2023 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. Contact email vely@vely.dev.