====== Setup a Lua Project ======

This section supposed you've already followed the previous note: [[lua-toolchain|Setup The Lua Toolchain]]

Create a new folder **new_project** that will hold our new project.
<code text>
$ mkdir new_project
$ cd new_project
</code>
Create the src directory
<code text>
$ mkdir src
</code>
Initialize the project with LuaRocks
<code text>
$ luarocks init --lua-versions "5.3" --no-wrapper-scripts
</code>
The project folder has been populated with some files: 
<code text>
$ ls -av
.gitignore
.luarocks
lua_modules
new_project-dev-1.rockspec
src
</code>
.gitignore is already setup to ignore **./lua_modules** **./.luarocks** which are not required into a repository.

===== Local and Project Related Modules =====
LuaRocks installs local or project related modules.
  * Local Module: are available for all the project. They are installed into **~/.local/lib** 
  * => Not covered here: we've already installed local modules by the other note: [[lua-toolchain|Setup The Lua Toolchain]] 
  * Project Related Modules: are available just for the project. They are installed into the project directory at **./lua_modules**

== Setup Project Related Modules  ==

The directory for the project related modules is already available at **./lua_modules**, but we still need to tell Lua where is located.

Create a file call **src/setup.lua**. This file tells to Lua that the project related modules are installed in **./lua_modules**
<code lua>
-- src/setup.lua
local version = _VERSION:match("%d+%.%d+")

package.path = 'lua_modules/share/lua/' .. version ..
    '/?.lua;lua_modules/share/lua/' .. version ..
    '/?/init.lua;' .. package.path
package.cpath = 'lua_modules/lib/lua/' .. version ..
    '/?.so;' .. package.cpath
</code>

== The main file  ==
We are almost done. Create the main file **src/main.lua**
<code lua>
-- src/main.lua
print('Hello!!!')
</code>
Run the main script and include the setup file. Note that the **setup** argument doesn't have the **.lua** extention:
<code text>
$ lua -l src/setup src/main.lua
</code>

== Lua Format  ==
We already have local installed the luaformat module.
Custom formatting preferences goes into the file .**lua-format** located in the project directory. For example, this are some customization:
<code bash>
# .lua-format
keep_simple_control_block_one_line: false
keep_simple_function_one_line: false
column_table_limit: 1
</code>
See all the available settings [[https://github.com/Koihik/LuaFormatter]]

Let's format the src/main.lua
<code text>
$ lua-format --in-place src/main.lua
</code>

== Lua Check  ==
Run the following to check all file in src
<code text>
$ luacheck src
Checking src/main.lua OK
</code>
You can try to add a unused variable the the **src/main.lua** as the follow:
<code lua>
-- src/main.lua
print('hello!!!')
local int = 1
</code>
Run again luacheck:
<code text>
$ luacheck src
Checking src/main.lua 1 warning
    src/main.lua:3:7: unused variable int
</code>
You can configure LuaCheck to be more permissive. LuaCheck settings go to the file **.luacheckrc** in your project directory.
<code lua>
-- .luacheckrc
allow_defined = true
</code>
See all the available settings [[https://luacheck.readthedocs.io/en/stable/config.html]]
==== Install Project Related Modules  ====
Install project related modules use LuaRock. For example, let's install the **ansicolors** module
<code text>
luarocks install --tree=lua_modules ansicolors
</code>
Edit the **src/main.lua** file as the following:
<code lua>
-- src/main.lua
local colors = require 'ansicolors'
print(colors('%{green}hello'))
</code>
Run the main script as following, which include the **setup** file
<code>
lua -l src/setup src/main.lua
</code>

==== Keep Your Modules in Sync: LuaRocks Spec file  ====
When you have a project related module that you want to **keep** in the repository, you have to configure the LuaRocks Spec file, new_project-dev-1.rockspec. In our example, let's add **ansicolors** module into the dependencies table: 
<code lua>
package = "new_project"
version = "dev-1"
source = {
   url = "*** please add URL for source tarball, zip or repository here ***"
}
description = {
   homepage = "*** please enter a project homepage ***",
   license = "*** please specify a license ***"
}
dependencies = {
   "lua ~> 5.3", -- /!\ it is a list: add a coma here
   "ansicolors"  -- /!\ the ansicolors module
}
build = {
   type = "builtin",
   modules = {}
}
</code>
Having the LuaRock spec file configured with dependencies, the project related modules will be installed with the following:
<code text>
$  luarocks install --deps-only new_project-dev-1.rockspec
</code>