sheepy

build system (sheepy) and package manager (spm) for C
git clone https://spartatek.se/git/sheepy.git
Log | Files | Refs | README | LICENSE

README.md (7169B)


      1 - [Install](#install)
      2 - [Dependencies](#dependencies)
      3 - [Starting a new project](#starting-a-new-project)
      4 - [Compilation](#compilation)
      5 - [Packages](#packages)
      6 - [Compiling multiple source files](#compiling-multiple-source-files)
      7 - [Creating classes](#creating-classes)
      8 
      9 sheepy compiles and runs C programs **without makefiles** and it has the ability to run as a C script with a hashbang.
     10 GCC (minimum 4.9) has to be installed for a working system.
     11 
     12 The build system is multiprocess by default and already built objects are reused.
     13 
     14 `sheepy` depends on [libsheepy](https://spartatek.se/r/libsheepy/file/README.md.html), `libsheepy` is installed during the installation process.
     15 
     16 Check out the [user guide](http://spartatek.se/libsheepyUserGuide/) to learn how to use sheepy and libsheepy, for more detailed information read the libsheepy reference documentation available at [http://spartatek.se/libsheepy/](http://spartatek.se/libsheepy/).
     17 
     18 The prefered C standard is `C11` because libsheepy has many **generics**, `C99` is supported but is much less convenient to use than C11 since there are thousands of functions in libsheepy (a function for each type and feature).
     19 
     20 - `sheepy` builds the executables and libraries.
     21 - `spm` is the package manager.
     22 
     23 Demo: [![asciicast](https://asciinema.org/a/sVPOkMKI951Nw8DBeLPxzNlo7.svg)](https://asciinema.org/a/sVPOkMKI951Nw8DBeLPxzNlo7)
     24 
     25 # Install
     26 
     27 Platforms:
     28 - Linux/GNU, Intel (Ivy Bridge or newer for DRNG RDRAND)
     29 - Linux/GNU, ARM (raspberry pi)
     30 - Android/Termux ARM
     31 - MacOS
     32 - FreeBSD
     33 - OpenBSD
     34 - DragonflyBSD
     35 - Alpine Linux (musl libc)
     36 - OpenIndiana (illumos, solaris, sunOS)
     37 - Haiku
     38 
     39 These commands install `sheepy` and `spm`:
     40 
     41 ```
     42 git clone https://spartatek.se/git/sheepy.git
     43 cd sheepy
     44 
     45 sudo -H ./install.sh
     46 ```
     47 
     48 To install sheepy in your home folder, run:
     49 ```
     50 ./homeInstall.sh
     51 
     52 # then add 'export LIBSHEEPY=...' and 'export PATH=...' in your startup scripts
     53 ```
     54 
     55 
     56 In Alpine Linux:
     57 ```
     58 # Apline Linux only
     59 apk add gcc libc-dev git
     60 # End Alpine Linux
     61 
     62 git clone https://spartatek.se/git/sheepy.git
     63 cd sheepy
     64 
     65 sudo -H ./install.sh
     66 ```
     67 
     68 In Termux:
     69 ```
     70 # Termux only
     71 pkg install git clang curl gdb
     72 
     73 git clone https://spartatek.se/git/sheepy.git
     74 cd sheepy
     75 
     76 ./installTermux.sh
     77 ```
     78 
     79 In OpenIndiana:
     80 ```
     81 # OpenIndiana only
     82 pkg install git gcc-8 system/header
     83 
     84 git clone https://spartatek.se/git/sheepy.git
     85 cd sheepy
     86 
     87 ./installOpenIndiana.sh
     88 ```
     89 
     90 ## Configuration
     91 
     92 The user configuration is located at `~/.sheepy/config.yml`.
     93 
     94 If the configuration file doesn't already exist, it is created when sheepy is executed for the first time.
     95 
     96 Settings:
     97 
     98 - _system_ install location of the sheepy and spm commands and global packages
     99 - _cflags_ flags for the C compiler
    100 - _lflags_ flags for the linker
    101 - _linkWithGold_ enable/disable gold linker (multithreaded linking)
    102 - _32bit_ generate a 32bit executable
    103 - _parallelSheepy_ enable/disable multiprocess build
    104 - _buildPath_ directory where the intermediary object files are stored
    105 - _key_ secret key to log on the `spm` registry
    106 - _testflags_ compile flags for tests
    107 
    108 When musl libc is installed on the system, configure sheepy to link against musl libc like this:
    109 
    110 ```
    111   cflags: -ggdb -std=gnu11 -fPIC -pipe -specs "/usr/local/musl/lib/musl-gcc.specs"
    112   # statically link  musl libc
    113   lflags: -static -specs "/usr/local/musl/lib/musl-gcc.specs"
    114   # dynamically link musl libc
    115   #lflags: -specs "/usr/local/musl/lib/musl-gcc.specs"
    116 ```
    117 
    118 The commands for installing musl libc are:
    119 
    120 ```
    121 git clone git://git.musl-libc.org/musl
    122 cd musl
    123 ./configure
    124 make
    125 sudo make install
    126 ```
    127 
    128 Then libsheepy has to be compiled using the musl libc headers, see [README.md](https://spartatek.se/r/libsheepy/file/README.md.html) in the libsheepy repo.
    129 
    130 # Dependencies
    131 
    132 `sheepy` and `spm` have some external dependencies:
    133 - GCC 4.9 or clang
    134 - Optionally gold linker, this can be disabled in the configuration (~/.sheepy/config.yml)
    135 - curl (`spm`)
    136 - tar (`spm`)
    137 - gzip or pigz (`spm`)
    138 
    139 # Starting a new project
    140 
    141 With `sheepy`:
    142 
    143 ```
    144 sheepy -n example
    145 
    146 # run:
    147 ./example.c
    148 ```
    149 
    150 To create new packages with `spm`:
    151 
    152 ```
    153 spm new example1 examples2
    154 
    155 # run:
    156 cd example1
    157 ./example1.c
    158 ```
    159 
    160 # Compilation
    161 
    162 To get help, run:
    163 ```
    164 sheepy -h
    165 ```
    166 
    167 To run a program:
    168 
    169 ```
    170 sheepy <C_SOURCE>
    171 ```
    172 
    173 To run as a script, add a hashbang at the top of the main c file:
    174 ```
    175 #! /usr/bin/env sheepy
    176 ```
    177 
    178 `libsheepy.a` is always linked and `pthread` is always enabled.
    179 
    180 minimal C source:
    181 
    182 ```c
    183 #! /usr/bin/env sheepy
    184 int main(int ARGC, char** ARGV) {
    185 }
    186 ```
    187 
    188 ## Compilation errors
    189 
    190 In some linux distributions (RHEL), this error occurs:
    191 
    192 ```
    193 ...git/libsheepy/release/libsheepy.a(libsheepy.o): In function `getMonotonicTime':
    194 ...git/libsheepy/release/libsheepy.c:50790: undefined reference to `clock_gettime'
    195 ```
    196 
    197 To solve this error, add __-lrt__ in compileSheepy.sh and in ~/.sheepy/config.yml in lflags
    198 
    199 # Packages
    200 
    201 To get help, run:
    202 ```
    203 spm help
    204 ```
    205 
    206 To install a package:
    207 
    208 ```
    209 sudo spm -g install sheepyExamples
    210 sudo spm -g install md
    211 ```
    212 
    213 The `searchReplace` requires libpcre to compile successfully, to install pcre:
    214 
    215 ```
    216 sudo apt-get install libpcre3-dev
    217 ```
    218 
    219 To create a new package:
    220 
    221 ```
    222 spm new packageName
    223 cd packageName
    224 ```
    225 
    226 # Compiling multiple source files
    227 
    228 sheepy doesn't use makefiles, it scans the `#include` lines in the source code to figure out what to compile.
    229 
    230 When an _include_ statement is found, sheepy searches for a C source file with the same name changing the extension from .h to .c.
    231 For includes in installed packages, the source files are already in the static library so the library is statically linked.
    232 
    233 For example, main.c:
    234 
    235 ```c
    236 #include "libsheepyObject.h"
    237 #include "test.h"
    238 #include "shpPackages/apkg/apkg.h"
    239 int main(int c, char **a) {
    240   XSUCCESS;
    241 }
    242 ```
    243 sheepy compiles main.c, test.c if it exists and statically link libapkg.a.
    244 
    245 # Creating classes
    246 
    247 As seen in previously `sheepy -n name` generates a new main file. `sheepy -C className` generates the files for a class called _className_
    248 
    249 In order to use the class, simply add `#include "className.h"` in a source file.
    250 
    251 The class templates has the methods inherited from the `baset` class, all the sheepy classes inherit from the `baset` class. The template has `TODO` comments showing how to extend the class.
    252 
    253 # Unit tests and memcheck
    254 
    255 sheepy and spm have commands for generating unit test and memcheck (valgrind) templates. The following is the instructions to generate and run the tests for <package name>:
    256 
    257 Create <package name> and edit package.yml to enable the tests:
    258 
    259 ```
    260 spm new <package name>
    261 cd <package name>
    262 vi package.yml
    263 ```
    264 
    265 Uncomment: `testBin`, `testCflags`, `testLflags`, `memcheckBin`, `memcheckCflags`, `memcheckLflags` and add the compilation flags as necessary
    266 
    267 Generate the test templates:
    268 
    269 ```
    270 sheepy -T
    271 ```
    272 
    273 Add the tests in test<Package name>.c
    274 
    275 __Run the tests__:
    276 
    277 - Unit tests:
    278 ```
    279 spm test
    280 ```
    281 
    282 Libcheck has to be available in the system since the unit tests are using it.
    283 
    284 
    285 - Memcheck:
    286 ```
    287 ./test<Package name>Mem.sh
    288 ```
    289 
    290 In memcheck tests, the unit tests are linked to libsheepyMemcheck which has container recycling disabled to easily identify the source of the leaks.
    291 Valgrind has to be available in the system.