-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.html
323 lines (321 loc) · 17.5 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<link rel="shortcut icon" type="image/x-icon" href="https://raw.githubusercontent.com/Livl-Corporation/livl-shell/master/img/livl_logo.ico">
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.17"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Livl Shell: Main Page</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectlogo"><img alt="Logo" src="livl_shell_logo.png"/></td>
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">Livl Shell
 <span id="projectnumber">0.1</span>
</div>
<div id="projectbrief">Livl Shell is an intermediate reimplementation of the bash shell in C language.</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.17 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="PageDoc"><div class="header">
<div class="headertitle">
<div class="title">Livl Shell Documentation</div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock-livl"><h1 align="center"><img src="livl_shell_logo.png" alt="" class="inline"/> </br> <b>Livl Shell</b> </h1>
<p>
</p><h4 align="center">An Intermediate Reimplementation of the Bash Shell in C </h4>
<h2><a class="anchor" id="autotoc_md0"></a>
Table of Contents</h2>
<ul>
<li><a href="#-prerequisites">📦 Prerequisites</a></li>
<li><a href="#-quick-start">🚀 Quick start</a></li>
<li><a href="#-makefile-guide">📚 Makefile Guide</a></li>
<li><a href="#-project-structure">📁 Project structure</a></li>
<li><a href="#-list-of-insane-livl-bash-commands">📝 List of insane livl-bash commands</a><ul>
<li><a href="#basic-commands">Basic Commands</a></li>
<li><a href="#inputoutput-redirection">Input/Output Redirection</a></li>
<li><a href="#pipelines">Pipelines</a></li>
<li><a href="#command-sequencing">Command Sequencing</a></li>
<li><a href="#batch-mode">Batch Mode</a></li>
<li><a href="#background-execution">Background Execution</a></li>
<li><a href="#history">History</a></li>
<li><a href="#alias">Alias</a></li>
</ul>
</li>
<li><a href="#working-with-the-documentation">Working with the documentation</a><ul>
<li><a href="#use-the-livl-shell-man-command">📖 Use the livl-shell man command</a></li>
<li><a href="#-doxygen-documentation">📜 Doxygen documentation</a><ul>
<li><a href="#-prerequisites-of-doxygen">📦 Prerequisites of Doxygen</a></li>
<li><a href="#-generate-the-doxygen-documentation">🚀 Generate the Doxygen documentation</a></li>
</ul>
</li>
<li><a href="#-gcov-test-coverage">🧪 GCOV test coverage</a><ul>
<li><a href="#-prerequisites-of-gcov">📦 Prerequisites of gcov</a></li>
<li><a href="#-generate-the-coverage-report">🚀 Generate the coverage report</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#️-pipelines">🛠️ Pipelines</a><ul>
<li><a href="#1-c-make-pipeline">1. C-Make Pipeline</a></li>
<li><a href="#2-static-pipeline">2. Static Pipeline</a></li>
</ul>
</li>
<li><a href="#-project-team">🧍🏽Project team</a></li>
</ul>
<h2><a class="anchor" id="autotoc_md1"></a>
📦 Prerequisites</h2>
<p>This project is developed in C language, so you need to have a C compiler installed on your machine to build it. It would be better to run it on a Linux distribution, but it has also been tested on macOS. It is possible to run it on Windows with the WSL (Windows Subsystem for Linux).</p>
<ul>
<li>gcc : <code>sudo apt install gcc</code></li>
<li>make: <code>sudo apt install make</code></li>
</ul>
<blockquote class="doxtable">
<p>To install the WSL on Windows, follow this <a href="https://docs.microsoft.com/en-us/windows/wsl/install-win10">tutorial</a>. </p>
</blockquote>
<h2><a class="anchor" id="autotoc_md2"></a>
🚀 Quick start</h2>
<p>Follow these steps to quickly get started:</p>
<ol type="1">
<li><b>Compile the Project</b>: Run the <code>make</code> command. This will compile the project and create an executable file called <code>livl-shell</code> in the <code>bin</code> folder.</li>
<li><b>Run the Executable</b>: You can run the executable by using the command <code>./bin/livl-shell</code> or <code>make run</code>.</li>
</ol>
<blockquote class="doxtable">
<p>😀 <b>Insane feature</b>: You can run the executable in batch mode by using the command <code>./bin/livl-shell -c "ls -l"</code>. </p>
</blockquote>
<ol type="1">
<li><b>Clean the Project</b>: Use the <code>make clean</code> command to clean the project.</li>
</ol>
<blockquote class="doxtable">
<p>💡 <b>Tip</b>: The command <code>make run</code> will compile and immediately run the executable. It is equivalent to running <code>make && ./bin/livl-shell</code>. </p>
</blockquote>
<h2><a class="anchor" id="autotoc_md3"></a>
📚 Makefile Guide</h2>
<p>The project uses a Makefile for managing build tasks. Here are some of the available targets:</p>
<ul>
<li><code>all</code>: Compile the project.</li>
<li><code>run</code>: Run the executable.</li>
<li><code>doc</code>: Generate documentation using Doxygen.</li>
<li><code>gcov</code>: Generate code coverage data using gcov and lcov.</li>
<li><code>package</code>: Package the project into a tar.gz file.</li>
<li><code>clean</code>: Remove all object files.</li>
<li><code>clean-gcov</code>: Remove all gcov-related files.</li>
<li><code>mrproper</code>: Perform a deep clean of the project.</li>
<li><code>clear</code>: Clear the console.</li>
</ul>
<p>You can use the <code>make help</code> command to display a brief description of each target.</p>
<h2><a class="anchor" id="autotoc_md4"></a>
📁 Project structure</h2>
<p>The project is structured as follows:</p>
<div class="fragment"><div class="line">livl-shell/</div>
<div class="line">├── bin/ # Contains the compiled binary</div>
<div class="line">│ └── livl-shell # Executable</div>
<div class="line">├── doc/ # Contains the Doxygen documentation</div>
<div class="line">│ └── html/</div>
<div class="line">│ └── index.html</div>
<div class="line">├── gcov/ # Contains the coverage report</div>
<div class="line">│ └── report/</div>
<div class="line">│ └── index.html</div>
<div class="line">├── include/ # Contains the header files</div>
<div class="line">│ └── file.h</div>
<div class="line">| └── ...</div>
<div class="line">├── src/ # Contains the source files</div>
<div class="line">│ └── file.c</div>
<div class="line">| └── ...</div>
<div class="line">├── livl-shell.1 # Manual of the livl-shell</div>
<div class="line">├── index.html # Static Livl Shell website</div>
<div class="line">├── history.txt # History of your commands</div>
<div class="line">├── aliases.txt # List of aliases</div>
<div class="line">└── Makefile # Makefile</div>
</div><!-- fragment --><h2><a class="anchor" id="autotoc_md5"></a>
📝 List of Insane livl-bash features</h2>
<blockquote class="doxtable">
<p>💡 The livl-shell is limited to run a maximum of 3 commands in a row. </p>
</blockquote>
<h3><a class="anchor" id="autotoc_md6"></a>
Basic Commands</h3>
<ul>
<li><code>ls</code>: Lists the files in the current directory.</li>
<li><code>cd</code>: Changes the current directory.</li>
<li><code>pwd</code>: Prints the current directory.</li>
<li><code>echo</code>: Displays a line of text.</li>
</ul>
<h3><a class="anchor" id="autotoc_md7"></a>
Input/Output Redirection</h3>
<ul>
<li><code>ls -l > output.txt</code>: Redirects the output of a command to a file.</li>
<li><code>pwd >> output.txt</code>: Appends the output of a command to a file.</li>
<li><code>wc -l < output.txt</code>: Counts the number of lines in the file.</li>
<li><code>cat << EOF</code> : let the user enter text until he types 'EOF' (You can change EOF by whatever you want). The text is then displayed on the screen thanks to the cat command.</li>
</ul>
<h3><a class="anchor" id="autotoc_md8"></a>
Pipelines</h3>
<ul>
<li>‘ls -l | grep ’.txt'`: Redirects the output of a command to another command. You can use single, double, or no quotes.</li>
</ul>
<h3><a class="anchor" id="autotoc_md9"></a>
Command Sequencing</h3>
<ul>
<li><code>sleep 4 && echo "Second command executed"</code>: Executes a command after another one.</li>
<li><code>false && echo "This won't be executed"</code>: Executes a command after another one only if the first one succeeded.</li>
<li><code>false || echo "This will be executed"</code>: Executes a command after another one only if the first one failed.</li>
<li><code>echo "Command 1"; sleep 3; echo "Command 2"; ls -l</code>: Executes multiple commands regardless of the success of the previous ones. The <code>ls -l</code> won't be executed because the shell is limited to run a maximum of 3 commands in a row.</li>
</ul>
<h3><a class="anchor" id="autotoc_md10"></a>
Batch Mode</h3>
<blockquote class="doxtable">
<p>⚠️ The command should be enclosed in quotes to ensure it is passed as a single argument </p>
</blockquote>
<ul>
<li><code>./livl-shell -c "ls -l|grep txt && echo heyyy"</code>: Executes a list of commands from the command line.</li>
<li><code>./livl-shell --command "echo livl"</code>: Executes a list of commands from the command line.</li>
</ul>
<h3><a class="anchor" id="autotoc_md11"></a>
Background Execution</h3>
<ul>
<li><code>sleep 3 & echo hey</code>: Executes a command in the background (the shell will not wait for the command to finish) and it will show you the job id of the background process (ex: <code>[1] 1234</code>).</li>
<li><code>pwd</code>: Running this command will display the job id of the background process terminated (ex: <code>[1] done sleep 3</code>).</li>
</ul>
<h3><a class="anchor" id="autotoc_md12"></a>
History</h3>
<p>The livl-shell has an ex history feature that allows you to view the history of your commands.</p>
<p><b>Experimental</b>: Use up / down and left / right arrows. To be able to use this feature, you need to go to the branch <a href="https://github.com/Livl-Corporation/livl-shell/tree/feat/history-navigation"><code>feat/history-navigation</code></a>. This feature is not available on the <code>master</code> branch because some issues have been detected when using the left / right arrows to move the cursor in the command line and the up / down arrows to navigate through the history. But feel free to contribute to this branch if you want to fix this issue. 😀</p>
<p>The history is saved in the <a href="history.txt"><code>history.txt</code></a> file.</p>
<h3><a class="anchor" id="autotoc_md13"></a>
Alias</h3>
<p>Livl-shell provide a basic alias support. <a class="el" href="structAlias.html" title="Struct that represents an alias.">Alias</a> can be defined only by editing the <code>aliases.txt</code> file. The syntax is the following:</p>
<div class="fragment"><div class="line">alias_name="command"</div>
</div><!-- fragment --><blockquote class="doxtable">
<p>Note that you can't use alias inside alias. </p>
</blockquote>
<p>For example, if you want to create an alias for the <code>ls -l</code> command, you can add the following line to the <code>alias.txt</code> file:</p>
<div class="fragment"><div class="line">ll="ls -l"</div>
</div><!-- fragment --><p>Then, you can run the <code>ll</code> command to execute the <code>ls -l</code> command.</p>
<blockquote class="doxtable">
<p>You can input arguments with your alias, as well as use pipes and redirections. For example, if you input <code>ll -m</code> it will be interpreted as <code>ls -l -m</code>. </p>
</blockquote>
<blockquote class="doxtable">
<p><a class="el" href="structCommand.html" title="Struct that represents a command.">Command</a> sequencing, pipes & redirections are <b>not supported</b> in aliases. <a class="el" href="structAlias.html" title="Struct that represents an alias.">Alias</a> can only work for a single command. </p>
</blockquote>
<h2><a class="anchor" id="autotoc_md14"></a>
Working with the documentation</h2>
<h3><a class="anchor" id="autotoc_md15"></a>
📖 Use the livl-shell man command</h3>
<blockquote class="doxtable">
<p>To edit the man you can download a TROFF Syntax Highlighter for Visual Studio Code. </p>
</blockquote>
<ul>
<li>The <code>man livl-shell</code> manual is located in the <a href="livl-shell.1"><code>livl-shell.1</code></a> file</li>
<li>To view the manual, run : <code>man ./livl-shell.1</code></li>
</ul>
<h3><a class="anchor" id="autotoc_md16"></a>
📜 Doxygen documentation</h3>
<blockquote class="doxtable">
<p>❓ Doxygen is a documentation generator, a tool for writing software reference documentation. </p>
</blockquote>
<h4><a class="anchor" id="autotoc_md17"></a>
📦 Prerequisites of Doxygen</h4>
<ul>
<li>Download doxygen : <code>sudo apt install doxygen</code></li>
</ul>
<h4><a class="anchor" id="autotoc_md18"></a>
🚀 Generate the Doxygen documentation</h4>
<ul>
<li>Run <code>make doc</code> to generate the documentation</li>
<li>To view the documentation, open the <a href="/doc/html/index.html"><code>index.html</code></a> file in the <code>doc/html/</code> folder.</li>
</ul>
<h3><a class="anchor" id="autotoc_md19"></a>
🧪 GCOV test coverage</h3>
<blockquote class="doxtable">
<p>❓ GCOV is a test coverage program. It helps you determine how much of your source code is being tested by your test suite. It is a useful tool for finding untested code. </p>
</blockquote>
<h4><a class="anchor" id="autotoc_md20"></a>
📦 Prerequisites of gcov</h4>
<ul>
<li>Download gcov : <code>sudo apt install gcov</code></li>
<li>Download lcov : <code>sudo apt install lcov</code></li>
</ul>
<h4><a class="anchor" id="autotoc_md21"></a>
🚀 Generate the coverage report</h4>
<ul>
<li>Run <code>make gcov</code> to generate the coverage report</li>
<li>To exit the coverage report, press <code>exit</code> two times (one for the shell and one for the coverage report)</li>
<li>To view the coverage report, open the <a href="/gcov/report/index.html"><code>index.html</code></a> file in the <code>gcov/report/</code> folder or run <code>gcovr -r .</code></li>
<li>Run <code>make clean-gcov</code> to clean the <code>gcov</code> folder</li>
</ul>
<h2><a class="anchor" id="autotoc_md22"></a>
🛠️ Pipelines</h2>
<p>Our pipelines are configured to be triggered on each <code>push</code> and <code>pull request</code> event on the <code>master</code> branch. We have two main pipelines:</p>
<h3><a class="anchor" id="autotoc_md23"></a>
1. C-Make Pipeline</h3>
<p>The <code>c-make</code> pipeline compiles the project using the <code>make</code> command.</p>
<h3><a class="anchor" id="autotoc_md24"></a>
2. Static Pipeline</h3>
<p>The <code>static</code> pipeline hosts the static website on GitHub Pages at the root of the repository. This allows access to the Doxygen documentation and the Coverage report at the following address: <a href="https://livl-corporation.github.io/livl-shell/">https://livl-corporation.github.io/livl-shell/</a></p>
<h2><a class="anchor" id="autotoc_md25"></a>
🧍🏽Project team</h2>
<p>The Livl team is composed of two members from the CNAM of Strasbourg:</p>
<table id="livl-table" align="center">
<tr>
<th class="livl-th"><img src="https://avatars.githubusercontent.com/u/19238963?v=4?v=4?size=115" alt="" width="115" class="inline"/><br />
<b>@FranckG28</b> </th><th class="livl-th"><img src="https://avatars.githubusercontent.com/u/62793491?v=4?size=115" alt="" width="115" class="inline"/><br />
<b>@jvondermarck</b> </th class="livl-th"></tr>
<tr align="center">
<td class="livl-td"><b>Franck Gutmann</b> </td><td class="livl-td"><b>Julien Von Der Marck</b> </td></tr>
</table>
</div></div><!-- PageDoc -->
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.17
</small></address>
</body>
</html>