Code Base Templates¶
Introduction¶
This document extends and provides examples to the Coding Style.
Template for a Translation Unit (aka Module)¶
/*
* Any appropriate description of the module.
* Copyright (C) 2020-2023 LuaVela Authors. See Copyright Notice in COPYRIGHT
* Copyright (C) 2015-2020 IPONWEB Ltd. See Copyright Notice in COPYRIGHT
*
* Portions taken verbatim or adapted from LuaJIT.
* Copyright (C) 2005-2017 Mike Pall. See Copyright Notice in luajit.h
*
* Portions taken verbatim or adapted from the Lua interpreter.
* Copyright (C) 1994-2008 Lua.org, PUC-Rio. See Copyright Notice in lua.h
*/
#include "..."
#include "..."
static void module_assert_something(lua_State *L, const GCtab *t)
{
/* Please comment all #else and #endif directives. */
#ifndef NDEBUG
lua_assert(...);
lua_assert(...);
lua_assert(...);
#else /* NDEBUG */
UNUSED(L);
UNUSED(t);
#endif /* !NDEBUG */
}
/*
* 1. Please do not append uj_ prefix for static routines.
* 2. Please do append module_ prefix for static routines.
* 3. Please do not forget about const.
* 4. If your routine (either static or a part of the module's public API)
* notifies a caller with a return code, use non-0 values
* for indicating errors, and 0 for indicating success.
*/
static int module_do_something(lua_State *L, const GCtab *t)
{
/* ...code... */
if (something_wrong)
return 1;
module_assert_something(L, t);
return 0;
}
/*
* If your routine answers a Yes/No question,
* use non-0 values for "yes", and 0 for "no".
*/
static int module_is_something(...)
{
return check_condition() ? 1 : 0;
}
/*
* For members of the module's public API,
* please append uj_module_ prefix.
*/
lua_State *uj_module_public_api()
{
/* ...code... */
}
Template for a Header File¶
/*
* Any appropriate description of the header.
* Copyright (C) 2020-2023 LuaVela Authors. See Copyright Notice in COPYRIGHT
* Copyright (C) 2015-2020 IPONWEB Ltd. See Copyright Notice in COPYRIGHT
*
* Portions taken verbatim or adapted from LuaJIT.
* Copyright (C) 2005-2017 Mike Pall. See Copyright Notice in luajit.h
*
* Portions taken verbatim or adapted from the Lua interpreter.
* Copyright (C) 1994-2008 Lua.org, PUC-Rio. See Copyright Notice in lua.h
*/
#ifndef _UJ_MODULE_H
#define _UJ_MODULE_H
#include "..."
#include "..."
/* Forward-declare where it makes sense: */
struct lua_State;
struct GCtab;
union TValue;
/*
* Please avoid using macros. For lightweight, always
* inlined interfaces use the following idiom:
*/
static LJ_AINLINE const TValue *uj_module_fast(lua_State *L, GCtab *mt)
{
return ...;
}
/* Function description. */
lua_State *uj_module_public_api();
#endif /* !_UJ_MODULE_H */
Flower Boxes¶
The Contents of Flower Boxes¶
In general a flower box (a comment placed right in the beginning of a file) consists of four parts:
- Module/Header description + LuaVela’s copyright note. Must be present in all files (both modules and headers) across the LuaVela code base.
- IPONWEB’s copyright note. Must be present in all files (both modules and headers) across the LuaVela code base created before the project was transferred to LuaVela organization on GitHub.
- LuaJIT-related copyright note. Must be present in all files that were adopted from the LuaJIT code base.
- PUC-Rio Lua-related copyright note. Must be preserved in all cases when Mike Pall placed this notice in the LuaJIT code base files.
Flower Boxes for Non-Core Code Base¶
CMake Files¶
# Purpose of the file.
# Copyright (C) 2020-2023 LuaVela Authors. See Copyright Notice in COPYRIGHT
Tools¶
Perl
#!/usr/bin/perl -w
#
# This is a tool for doing blah-blah-blah
# Copyright (C) 2020-2023 LuaVela Authors. See Copyright Notice in COPYRIGHT
C
Follows the same rules as for the core code base. Obviously LuaJIT and PUC-Rio Lua must not be mentioned.
Tests¶
Lua
Verbose Version
-- Description of the chunk (what it actually tests, etc.).
-- Copyright (C) 2020-2023 LuaVela Authors. See Copyright Notice in COPYRIGHT
Acceptable Default
-- This is a part of uJIT's testing suite.
-- Copyright (C) 2020-2023 LuaVela Authors. See Copyright Notice in COPYRIGHT
Perl
Verbose Version
#!/usr/bin/perl
#
# Description of the test (what it actually tests, etc.).
# Copyright (C) 2020-2023 LuaVela Authors. See Copyright Notice in COPYRIGHT
Acceptable Default
#!/usr/bin/perl
#
# This is a part of uJIT's testing suite.
# Copyright (C) 2020-2023 LuaVela Authors. See Copyright Notice in COPYRIGHT
C
Verbose Version
Follows the same rules as for the core code base. Obviously LuaJIT and PUC-Rio Lua must not be mentioned.
Acceptable Default
/*
* This is a part of uJIT's testing suite.
* Copyright (C) 2020-2023 LuaVela Authors. See Copyright Notice in COPYRIGHT
*/
Shell Runners
Verbose Version
#!/bin/bash
#
# Description of the runner.
# Copyright (C) 2020-2023 LuaVela Authors. See Copyright Notice in COPYRIGHT
Acceptable Default
#!/bin/bash
#
# This is a part of uJIT's testing suite.
# Copyright (C) 2020-2023 LuaVela Authors. See Copyright Notice in COPYRIGHT
Copyright Notice Format¶
There is no explicit policy on the matter, but for the sake of cross-project consistency following format/spelling is adopted:
Copyright (C) 2020-2023 LuaVela Authors. See Copyright Notice in COPYRIGHT