about summary refs log tree commit diff stats
diff options
context:
space:
mode:
-rw-r--r--COPYING13
-rw-r--r--README.md172
2 files changed, 185 insertions, 0 deletions
diff --git a/COPYING b/COPYING new file mode 100644 index 0000000..b561af6 --- /dev/null +++ b/COPYING
@@ -0,0 +1,13 @@
1Copyright 2023 Case Duckworth <acdw@acdw.net>
2
3Permission to use, copy, modify, and/or distribute this software for any purpose
4with or without fee is hereby granted, provided that the above copyright notice
5and this permission notice appear in all copies.
6
7THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
8REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
9FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
10INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
11OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
12TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
13THIS SOFTWARE.
diff --git a/README.md b/README.md new file mode 100644 index 0000000..096df26 --- /dev/null +++ b/README.md
@@ -0,0 +1,172 @@
1# MISC
2## Manually Installed and Source Compiled
3
4*an easier way to source-compile programs and stuff*
5
6## why?
7
8I run Debian Stable, which is great for the most part. However, there are some
9programs that I want to have a newer version of than what's in the Debian repos
10--- and the easiest way to install those is by compiling them myself from
11source.
12
13However, compiling from source can be complex and fiddly, which makes it ripe
14for automation! `misc` is my submission into the wide and varied world of
15software building software. I use it and not other solutions for the following
16reasons:
17
18- It's written in bash and extended in bash, the _lingua franca_ of Unix-ish
19 operating systems. I could've done it in POSIX sh, but I really wanted to
20 have arrays.
21- Because it's written in bash, it's usable anywhere bash is installed. So most
22 places.
23- It doesn't make too many assumptions. It only _barely_ installs dependencies,
24 and really is just a wrapper around the ol' `./configure`, `make`, `make
25 install` workflow we all know and love.
26- It's (_going to be_) extensible to cover uses I haven't thought of yet.
27
28## usage
29
30Basic usage is simply running `misc PLAN`, where `PLAN` is a file in
31`$MISC_PLAN_ROOT` (default: `$XDG_CONFIG_HOME/misc`) that details how to install
32a program. There's no differentiation between `install` and `update`, and
33there's currently no method of removing a program (in my experience,
34_uninstalling_ is more bespoke than installing and would require greater
35complexity).
36
37Programs are installed under `$MISC_INSTALL_PREFIX`, which is `$HOME/.local` by
38default. I like putting programs under the `$HOME/.local` prefix for a few
39reasons:
40
41- They don't require `sudo` to install
42- `$HOME/.local` already includes `$HOME/.local/share`, which is
43 `$XDG_DATA_HOME` and already includes a bunch of stuff
44- It's pretty easy to add `$HOME/.local/bin` and the like to `$PATH`.
45
46Of course, you can change `$MISC_INSTALL_PREFIX` to whatever you like, either in
47your shell's initiation file or in `$MISC_CONFIG`, or
48`$XDG_CONFIG_HOME/misc/misc.sh` by default.
49
50### `misc.sh`
51
52In this section, I'll discuss all the environment variables that `misc` itself
53uses. Plans use a lot of environment variables too, but those are in the
54following section (_Plans_).
55
56- `$MISC_CONFIG` defines the location of `misc`'s configuration file. This is a
57 shell script that's sourced before building anything. Default:
58 `$XDG_CONFIG_HOME/misc/misc.sh`.
59- `$MISC_REPO_ROOT` is the directory that all programs are downloaded or cloned
60 to. Default: `$XDG_DATA_HOME/misc`.
61- `$MISC_PLAN_ROOT` is the directory where `misc` will search for plan files.
62 Default: `$XDG_CONFIG_HOME/misc`. *There might be a better place for these
63 but until I can think of one this is where it'll be.*
64
65The following variables are used when processing plans, but they're
66`misc`-specific. You might want to reference these in your plans.
67
68- `$MISC_PLAN`: The name of the program to build and install or upgrade.
69- `$MISC_FULL_PLAN`: The full path of the plan file; formed from
70 `$MISC_PLAN_ROOT/$MISC_PLAN`.
71- `$MISC_REPO`: The local directory holding the source of the program being
72 built. Most tasks should be performed within this directory.
73- `$MISC_INSTALL_PREFIX`: The installation `PREFIX` variable that's invoked when
74 `make`ing the program. It can also be used in `$CONFIGURE_ARGS` and the like,
75 which see.
76- `$MISC_DONE`: A sigil variable indicating when building is done. If this
77 variable is non-empty, `misc` will detect the build/install as
78 done---otherwise, it will run the default build/install flow. The following
79 functions automatically set `$MISC_DONE`; of course you can set it yourself in
80 a plan.
81 - `repo_pull`
82 - `repo_ready`
83 - `make`
84 - `make_install`
85 - `configure`
86
87### Plans
88
89"Plans" are what `misc` calls the instruction files to install programs. There
90are some examples in the `examples/` subfolder of this repo.
91
92Plans are simply bash source files defining some variables and optionally
93specifying build/install steps. There is a default build process that `misc`
94will use if it does not detect any build steps being defined in the plan file.
95Below are the variables and functions in the `misc` environment at build-time;
96of course since plans are just bash files, you can define your own or really do
97anything you want.
98
99### Plan variables
100
101- `$SOURCE`: The source URL of the program's file or repository.
102- `$CHECKOUT`: The Git checkout to clone. Default: `master`.
103- `$CONFIGURE_ARGS`: Arguments to pass to the `./configure` script.
104- `$MISC_DEPENDENCIES`: Dependencies to install via `misc` before installing the
105 planned program.
106- `$APT_DEPENDENCIES`: Depenedencies to install via `apt` before installing the
107 planned program.
108
109### Plan functions
110
111There are a number of functions defined in `misc` that plans inherit into their
112environments. You can use all of these in plan files, though this is not an
113exhaustive list. This is, however, all the functions that I think you might
114find useful in a plan file.
115
116#### Utility functions
117
118- `die CODE MESSAGE...`
119- `run COMMAND...`
120- `cmd COMMAND...`
121- `with_repo COMMAND...`
122
123#### Building and installation functions
124
125- `install_deps`
126- `repo_pull [CHECKOUT]`
127- `repo_download_extract`
128- `repo_ready [TARGET...]`
129- `repo_nuke`
130
131#### Plan convenience aliases
132
133Since `misc` and plan files are simply shell scripts, you could just write the
134direct commands to download, extract, and install a given program. However,
135then there's little reason to use `misc` --- so I've included a few thin wrapper
136functions around common commands that operate in the `$MISC_REPO` directory and
137specify a prefix of `$MISC_INSTALL_PREFIX`.
138
139- `make [ARG...]`, `git [ARG...]`, `tar [ARG...]`: These run their commands with
140 a `-C $MISC_REPO` argument for ease of use. If you want to use the raw
141 commands, `_make` `_git`, and `_tar` are defined for those.
142- `make_and_install [TARGET...]`: First runs `make` with the supplied `TARGET`s,
143 then runs `make install`. Note that `make` is the `make` defined above, that
144 is, the `misc`-ified one.
145- `configure [ARG...]`: This runs `./configure` in the `$MISC_REPO` directory.
146 If called with `ARG`s, it uses those; otherwise it uses the arguments defined
147 in `$CONFIGURE_ARGS`.
148
149## caveats & todos
150
151As you can see from these variables and functions, `misc` is currently optimized
152for a `./configure; make; make install`-style build system on a Debian-derived
153host. Again, since a plan file is just a shell script, you can run any commands
154you like in there---and it'll still take advantage of `misc`'s standardized
155prefix and build root. See the `keepassxc` example for an example using the
156`cmake` system, and `lieer` for a `python`-based system.
157
158Of course, it'd be ideal to have these vagaries somewhat abstracted-away by
159`misc`, so at some point in the future I'll include some sort of "add-on" system
160where a user will be able to define further functions to fit alternative build
161systems. I'll also want to figure out a way to generalize dependency
162installation across distributions, since the current solution (`apt install`
163hardcoded into the script) is brittle.
164
165If you have any ideas about these todos or how to solve the problems I'm
166currently facing, feel free to [email me][mailto:git@acdw.net?subject=misc] with
167your ideas.
168
169## license
170
171`misc` and all other code in this repository is licensed under the terms of the
172ISC license. See COPYING for details.