-
Notifications
You must be signed in to change notification settings - Fork 0
Using FreeMyCode
First things first, you need to understand how FreeMyCode tool basically works. As mentioned in the previous pages of this wiki, FreeMyCode uses some files to configure itself, build the text blocks to be added on top of all relevant files of your project directory, etc.
This step of configuration could be divided in 3 categories:
- User configuration files
- License (or any piece of text) block you want to use
- Custom tags, such as author's name, contributors, website url, etc.
- FreeMyCode configuration files and resources (more or less "private" ; regular users may not modify those files)
- File-type based data collection : gathers instruction for each supported languages
- Pre-processed general use licenses (known as "Spectrums" in FreeMyCode's workflow)
- Raw general use licenses
- Direct user input
- These inputs might be command line arguments as well as GUI-based parameters (NOTE: GUI is not implemented yet)
Note: all necessary files are embedded in FreeMyCode installation folder, as well as templates to help the user to write his/her own configuration files.
As you may have already noticed, new users may not start sending direct input to FreeMyCode. Instead, one may focus on writing / modifying the following configuration files:
You may use whatever license you want. Simply bear in mind that FreeMyCode only knows about a license if it is already present in FreeMyCode Install/Resources... before the app starts. There is no special formatting, you can write what you want or pick one license over-the-shelf, and customize it to meet your needs. The only thing you need to do, for FreeMyCode to understand and use your license, is to create a file called "License.txt" and write your License "as is" inside.
Note : FreeMyCode Installation folder embeds some useful scripts and binaries which could be used to individually process a new License and obtain the corresponding "Spectrum". This is how we can extend FreeMyCode licenses database, simply move the new Spectrum file to the Install folder, inside Resources/Spectrums
Secondary_input.json file, despite its awful name, is used to tell FreeMyCode how to write custom tags. It only requires a top node "Tags", and you are ready to go! Simply remind to use an appropriate tool to check if your json writing style is valid (I've had quite a hard time back in the days figuring why I could not write valid json, until I realized I forgot a comma somewhere!). As an example, one may find useful to use a tool such as Jsonformatter to check for any writing mistakes. Some other tools such as Visual Studio Code could also be of help, feel free to use your own!
Back to Secondary_input.json, you may find a template which could be used to write your own kind of file:
{
"Tags": {
"Author": "bebenlebricolo",
"Contributors": [
"Dummy author 1",
"Dummy author 2",
"Dummy author 3"
],
"License": {
"name": "GPLv3",
"url": "https://www.gnu.org/licenses/quick-guide-gplv3.html"
},
"Organisation": {
"type": "Independant",
"name": "bebenCorp",
"url": "https://github.com/bebenlebricolo"
},
"Date": "30/04/2018",
"Custom Tag 1": "Hello World",
"Custom Tag 2": "My Super Duper Cool coffee",
"Custom Tag 3": "I want more tags!!!"
}
}This file will be processed by FreeMyCode, and will then be used to write the same data atop each targeted file. The output of this process has a YAML-like structure, which aims to be more "human-readable" than any other data structure. It has been used mainly for ease of reading. Here is the result of the above example, written down into a C++ header:
/*
------------------
@<FreeMyCode>
FreeMyCode version : 1.0 RC alpha
Author : bebenlebricolo
Contributors :
Dummy author 1
Dummy author 2
Dummy author 3
License :
name : GPLv3
url : https://www.gnu.org/licenses/quick-guide-gplv3.html
Organisation :
type : Independant
name : bebenCorp
url : https://github.com/bebenlebricolo
Date : 30/04/2018
Custom Tag 1 : Hello World
Custom Tag 2 : My Super Duper Cool coffee
Custom Tag 3 : I want more tags!!!
<FreeMyCode>@
------------------
*/This files contains the internal configuration of FreeMyCode. You may focus on the languages properties, pointed by the "Languages" node. To add rules, simply add one "Extension" or "Extension array" node and fill it with the targeted extension(s) name. Then, you may fill the supported comment scheme by adding some properties such as :
- "Bloc comment opening" (sorry for misspelling, I should fix it some day !)
- "Bloc comment closing"
- "Single line comment". Some languages may not implement all of those comment markers, it is totally fine to only set the "Single line comment" property. However, if using block comments, it is mandatory to provide opening and closing markers, otherwise FreeMyCode may fail on parsing / writing valid comments.
Here is a classic scheme for a new language support insertion :
{
"Extension" : ".c",
"Bloc comment opening" : "/*",
"Bloc comment closing" : "*/",
"Single line comment" : "//"
}Note 1 : this C++ style single line comment is supported by C standard since C99, it may not fit all C standards. Please double check your configuration first if you are using a C flavor which is older than C99
Note 2: all properties type is [key]:[value] ; both "key" and "value" being strings. No literals could be used in those configuration files.
Note 3: as one may notice, FreeMyCode works with file extensions. It is not able (yet?) to detect languages flavors using dedicated parsers. This means that if one file contains code written in, let's say, C, and its extension is wrong (such as .py, which stands for Python files), FreeMyCode will not detect that it is writing with the wrong language set !
Here is a more complete example of FreeMyCode Config.json writing style :
"Languages": [ //"Languages" node uses an array to store data
{ // First data element pf "Languages" node
"Extension array": [ // This is another array element : it stores a list of extensions
".cpp", // Array is filled with supported extensions
".c",
".h",
".hpp",
".cs",
".js"
],
"Bloc comment opening": "/*", // Block comment beginning marker
"Bloc comment closing": "*/", // Block comment ending marker
"Single line comment": "//" // Monoline comment (C++ style comments)
},
{ // 2nd element of "Languages" node array
"Extension": ".vb", // This node refers to single extensions ; this is a key-value binding only
"Single line comment": "'" // Some languages only implements a restricted set of commenting rules
}Now that the configuration step is behind us, we may start to actually talk to FreeMyCode! The first thing we need to do is gather the required files and check their paths. As FreeMyCode provides a simplified Python frontend (command line interface), we will focus on what it needs : simply ask it what it wants!
On Linux, open a terminal (ctrl+alt+T) and navigate to where you want FreeMyCode to run:
cd my_very_own_directoryNote for Windows users: find the appropriate toolset that works for you, such as git-for-windows and you may use the same input as Linux users. Simply open a terminal and redo the same steps
Then, identify the FreeMyCode installation folder. As FreeMyCode is totally 'portable', you can simply put it wherever you want, even aside to the folder you are about to process. Once this is done, you can issue the following command :
python3 <FreeMyCode Install Folder>/Scripts/Multi-Platform/LaunchFreeMyCode.pyNormally, this command shall reply this to you:
Current working dir is = <my_very_own_directory>
[ ERROR ] : Args count is too small, please check your input
---------- USAGE ---------
This tool is used as an abstraction layer for FreeMyCode user
Usage example : $ python LaunchFreeMyCode.py <InstallationFolder> <TargetedDirectory> <RessourcesDirectory>
Where :
InstallationFolder stands for the FreeMyCode installation folder
TargetedDirectory is the project's directory to be analysed
RessourcesDirectory is the directory where the user may store ressources files
Note :
Installation folder may contain :
* bin/ folder
* Config.json file
* Ressources/ folder
* Ressources/Spectrums folder
* Ressources/AvailableLicenses folder
RessourcesDirectory folder may contain :
* SecondaryInput.json file
* License.txt file -> License to be used throughout the project
-> Note 2 : License.txt should have EXACTLY that name for the program to start.
As you may notice, this frontend ask for a very few input folders. Starting from them, it will then inspect each arguments and look for specific files. If everything is setup correctly, FreeMyCode will start processing your targeted directory.
If you've made it this far, you probably noticed FreeMyCode has a lot to tell about what it is doing. Probably too much actually. Fortunately, this could be modified by modifying LaunchFreeMyCode.py, or directly using the FreeMyCode command line prompt. The last thing you can do is to modify this behaviour directly in FreeMyCode.cpp and recompile it thereafter, however it requires you to dive into FreeMyCode source code (a little).
I hope (really!) that logs are self-explanatory, however it might be a bit overwhelming to dive into all FreeMyCode logs and stuff. You will find some information about how the process goes, and FreeMyCode will tell you if something is wrong, or missing. Some of those logs tells you which file it is currently inspecting, what kind of extensions were detected in the process, which ones are supported, what kind of licenses it is currently inspecting, etc. As FreeMyCode only uses one execution thread at the moment, all operations are executed sequentially. Then it is rather easy to understand how FreeMyCode works.
Last but not least, one interesting feature of FreeMyCode is to detect previously licensed files. This is actually one of the key feature of this tool, without which it will be unsafe to run FreeMyCode on your projects. Such information could be found as well in FreeMyCode logs; thanks to it, you might easily find the name of the license and how close it is to what is actually written down in the files.