one-file (1f) faq

FAQ
===

Q: a question?
A: the answer.
X: an detailed explanation.

Q: What is the criteria for a tool or utility to be included in the main one-file (1f) project?
A: uses one-file (1f) skeleton, has "-1f" in program name.
X: basically, you source will contain everything the skeleton source does, which handles the command line switches '--1f', '--source|--src', '--src-size' and '--src-type', plus the console help for output '--1f'. The licence in the skeleton is just an example, it can be anything you prefer, and the defult may change at some point if enough people aggree on a better one (eg. CC3). The skeleton also defines the basic one-file (1f) blocks, which allow one-file (1f) source tools to interact with your source code.

Q: what if I dont want "-1f" at the end of my program name?
A: everything else in your source related to one-file (1f) can stay, "not a problem".
X: there are plenty of projects that qualify as one-file (1f) (eg 'sfontview.c'), some of which will never make it into the main one-file (1f) project (SliTaz OS 'tazBrowser'), but may eventually attain one-file (1f) conformity. For example, 'tazBrowser' uses GTK+ and X windows, yet it is still a single source file (libwebkit) web browser project.

Q: doesn't the source part get loaded into memory as well as the binary part of the program?
A: no, that why its works so well, one-file (1f).
X: all known file systems that are used by an OS to execute a program record the length of a file in the file system, not it the program. Most OS store a "program header" in a particular format (like elf, coff, a.out) with contains the lenght of the program binary, not the program file length.

Q: I execute or compile binary blobs, is one-file (1f) still useful?
A: yes, definitely, but maybe not append source in most cases.
X: one case where the above explanation is not true is when your OS loads and executes binary blobs (arbitrary binary data). Unless you tell it to only load X bytes, it will also load the attachment into memory. However there is (mostly) no point in appending the source in this situation. Unless possibly you are writing compiler or OS for a new platform, even so, you program needs to be able to produce the attached source out to file somewhere.

Q: I want to use one-file (1f) on a Mac OS (or another that contains fork data), is this possible?
A: yes, but you are recomended to test thoroughly, before releaseing your program into the wild.
X: without experimenting on said OS (like MacOS, OSX, NextOS, etc) it should not matter, especially if the compiled binary already contains the fork data, before appending. It really depends on how the OS handles and processes fork data, test it, there will be a solution that allows one-file (1f) to work success fully as intended.

Q: I use OSX, which already contains a filesystem in its program package distribution format (DMG), how does onefile fit into that?
A: You can still append the source to the actual binary file, or you can place it seperately, in the same place as the binary, in the DMG.
X: A DMG is a custom form of a standard archive format, with a specific layout, and a .DMG extension. In the same way as Id Software use .ZIP format, using only store compression, to package a filesystem structure under their game root, in their .PAK format. Or Debian uses TAR to compress "control.tar.gz" (containing 'dpkg' instructions and packaging information), "data.tar.xz" (or .tar.gz, tar.bz2, containging files in a filesystem layout), and "debian-binary" (a text file containing format information, like version). At the end of the day the binary of your program is there (with or without fok data) and you can append your one-file (1f) source to it.

Q: do I have to write code with C++ language (according to your examples)?
A: no. any language, with any compiler can be used.
X: You may notice that all current .CPP sources are plain ASCII (not uni-code UTF8 or UTF16) and their language semantics are actually C. This was done on purpose, basically to show how easy it is to write C++, plus leverage access to C++ in the development, or learning, process. one-file (1f) is as much about teaching, as it is about source accessability, or simplicity.

Q: do I have to use the GNU C++ compiler (according to your examples)?
A: no. Any compiler is fine, as long as Joe Average has access to it in the future.
X: You can a full blown BSD or GNU compiler toolchain, or something simple like VCC. Or a cross-compiler like ASM65 (but you'll need to add asembler routines to extract the attachment). On MSX, you can even use HiSoft C or HiTech C packages. The only real important thing is how easily will you be able to compile it in the future, if you dont already have the appropriate toolchain. Will you be able to find one.

Q: I want to use one-file (1f) to write (X) Windows apps, with a library other than SDL 1.2, can I?
A: yes, but drop the "-1f" from the program name, everything else can stay.
X: one-file (1f) programs are designed not to require any overhead that a bare system cant supply. All commands output commandline switch information that can be managed by pipes (|) on the console, even the SDL apps (which gets started after one-file (1f) switch processing). Nowadays, most platforms wupply a framebuffer console, which means they can do graphics on the console, so usually there is also a port of SDL 1.2.

Q: I don't want to use SDL 1.2 for framebuffer programming, can I?
A: yes (drop the "-1f" from the program name), and no
X: yes you can use any graphics library, but some are aging now, and SDL 1.2 is available on a lot (if not most) platforms. 'directfb' is not always available, and sometimes does not work well with SDL as a backend (you need correct settings in "/etc/fb.modes" & ".directfbrc" and they are machine specific). 'SVGAlib' is not usually uptodate for current library versions. The other main reason for using SDL 1.2, is that it is substantially smaller that SDL2, with the main library being 180Kb compared to 2Mb. enuf said.

Q: I want to use SDL2?
A: yes (drop the "-1f" from the program name), and no
X: yes you can use SDL2 graphics library, but alot of situations will not allow your one-file (1f) tool or utility to run: 1) the main library being 2Mb compared to SDL 1.2's 180Kb. 2) some systems or platforms will never have SDL2 ported, as they dont have enough physical resources (disk space or memory). 3) SDL2 still has issues with fullscreen windows on some platforms (as opposed to fullscreen on console).

Q: So if its not a console app, or SDL 1.2 console app, I should not have "-1f" on the end of my program name?
A: yes, everything in code can stay, including the one-file (1f) switches.
X: A one-file (1f) console app, or SDL 1.2 console app can still be used on a (X) Windows GUI, windowed or fullscreen. If a program name ends with "-1f" you can assume it will run on a non-windowing system, and use SDL 1.2 as primary underlying interface for graphics, even if there are other higher level libraries handleing the GUI stuff (eg: GUIchan, Pango, SGE, libtao, etc). NOTE: it is possible to compile both GTK & QT without X, but you need to "./configure" them with a different PREFIX than "/usr" or even "/usr/local", "/opt" is a good option. If an app runs on console, or framebuffer console, appends the source, it can have "-1f" at the end of the program name, in which case it will get added to the main one-file (1f) project (at some point).

Q: My one-file (1f) SDL 1.2 app runs differently on different platforms, why?
A: its an SDL 1.2 (or sub-library) thing
X: for example, alot of people think SDL_ttf only handles TTF format TrueType fonts. It doesn't, it's just that their version of SDL_ttf wasn't './configure'd with OTF, PCF, bitmap, ADF, Type 1, BDF, FON, Windows FNT, or other font support. There is a source file fitting one-file (1f) ideals, called "sFontView", which I use to "display them all", on X or console, which will be added soon.

Q: how do I support more formats with SDL_image or SDL_mixer?
A: make notes in your source, append patches with source as ZIP format.
X: the easiest way for everyone to benifit, is to get them added "upstream", where they will filter down to most (if not all) distributions. You need to consult SDL 1.2 documentation and library code if you want to write your own. SDL_mixer can use MIKMOD or MODplug, so additional formats are not dependant on SDL 1.2, and will become available when they get "upstream" updates on your OS. NOTE: SDL_gfx extends SDL_image, while (Icculus.org) SDL_sound extends SDL_mixer

Q: How do I write a SDL console app that will pull Adobe Shockwave Flash (.SWF) content?
A: you need to implement a Pepper API interface in your app, and use SDL_net.
X: PPAPI, used by Chrome, about to be supported by Mozilla FireFox (2017), is a far superior plugin interface than the aging NSPlugin API originally developed for Netscape browser. Adapt the sources from "freshplayer" (which is a PPAPI => NSPAPI wrapper) to get this to work. If your platform has a Flash player with a browser plugin (like Gnash or LightSpark) then write a NSPAPI interface for them (eg. "/usr/lib/mozilla/plugins/flash-mozilla.so"). NOTE: On Linux, PepperFlashPlugin (most Flash plugins) are compiled with GTK+ (GTK2), so you need to take that into account (see above).

Q: How do I write an app that uses touch screen input?
A: find a library that can do it, make notes in your source.
X: There is a library for GTK+ that handles touch screen. QT has touch screen built in, usually as an option. A library that works over the top of SDL is going to be more portable, as it supports mouse interface. General Purpose Mouse (GPM) is a console mouse driver that works on text mode. It may or maynot interfere with SDL 1.2, but turns itself off when X is running on active tty (7). There are onscreen keyboards available, just make sure to handle things if people dont have a mouse/touchscreen and do have a keyboard.

Q: I have only one source file, but lots of data file. Can I still use my one-file (1f) program to distribute the source?
A: yes
X: if you release in into the wilds of the net, make your last compile with SRC-TYPE ".zip". For you own development, or local installation, you can append only the src to the compiled program, as long as you can easily see (or access) the other files. Its really up to you.

Q: as a system administrator, I really dont like the idea of users having access to source. Is one-file (1f) really that good in my situation?
A: yes. (dont be a control phreak).
X: if your permissions are managed correctly, then yes, there is "not a problem" with users having access to the program sources, they can run there own modified version, if they know what one-file (1f) is. If you are talking about critcal tools, then I suggest you keep a current development version seperately that contains the attachment, out of your $PATH, and a release version that doesn't have source attached, inside your $PATH.

Q: OK, but I dont like the idea of having extra files floating around, even if they are outside $PATH, how does one-file (1f) help me keep "a tidy house"?
A: because it IS one-file (1f).
X: after any development work has finish, you dont need to keep any development files lying around (unless you are constantly modifying source on say weelky or daily basis). Simply maintain it in its one-file (1f) form (inside your $PATH even). This also stops versioning problems too, as the extracted source is for the version of the program you are currently using.

Q: as a programmer (or Administrator of Hacker renown), I want to access the appended ZIP format as a filesystem from within my program. Can I really achieve this with one-file (1f)?
A: yep. For example, PhysicsFS will help you do it.
X: What ever library or way you use to access the attachment, you may need to pass an initial offset to the beginning of the .ZIP part of the file (its file_size-SRC_SIZE), to get things working correctly. Or otherwise dump it to a 'temp'orary folder first (internally), before accessing it (remember to clean up afterwards). This is a brilliant idea by the way, glad you thought of it.

Q: as a programmer (or Administrator of Hacker renown), I want to update the appended ZIP from within my program. Can I really achieve this with one-file (1f)?
A: yep. Again, PhysicsFS will help you do it.
X: This is a bit trickier, but not much more so, as you still know the offset to the attachment, however SRC_SIZE is obviously going to change, and that may affect your program binary size also. If you were to use a 64bit unsigned number to store PRG_SIZE and SRC_SIZE then you will be able to get around that problem. This answer is easier in assembler, because you can JMP past 2x 64bit values (16 bytes) that exist at an unchanging place (usually) near the beginning or you code. This is also a brilliant idea by the way, glad you also thought of it.

Q: Ok, but you did not explain exactly how to do it with code examples, did you?
A: yes. There will be an example available for download in the near future.
X: But even then, it will probably not fit your use case 100%. And how to do it in other than C semantics .CPP will be left up to others. Feel free to contribute your one-file (1f) creation to the one-file (1f) project to help others out (with both your tool and your source).

Q: I have a project that I think will benefit from one-file (1f) development, but it requires extra commands (or files) that are not part of the compile process. How does one-file (1f) work in this situation?
A: use custom one-file (1f) blocks
X: one-file (1f) outlines a way which 99% of people can easily understand what is required to get the most out of your one-file (1f) program and one-file (1f) source. Extra files can be maintained within a single source file (eg. /* one-file (1f) 'Makefile'). At the time of writing, "/* one-file (1f) '" is an identifier (for automation) at the beginning of a line, signifying everything after that, upto the next single quote mark ('), is a file name. I am willing to also state here and now, that everything after "/* one-file (1f) $ " (ends with dollar,space) to the end of the line (EOL), is a super-user command. While everything after "/* one-file (1f) # " (ends with hash,space) to the end of the line (EOL), is a regular-user command.

Q: I have extra files and/or command in my one-file (1f) source, how do I make them work with copy and paste, the same way one-file (1f) compile command work?
A: on linux (read: posix), use \ on the end of the line.
X: only multi-line commands designed to be pasted into a console are going to be affected. Everything else till the next "*/" at the beginning of a line should be ASCII (read: plain text). 

Q: wont extra files and/or commands get in the way of the compiler?
A: no. They are within block remarks, so they get skipped over.
X: In C/C++ (and many other languages, or language semantics, like DocBook) "/* anything here */" is a block remark, especially if they begin (/*) and end (*/) at the start of a line.

Q: OK, but I need to put remarks within those extra file blocks?
A: so, you want me to code program too? email it to /dev/null 
X: seriously, the technique you are looking for is called "obfuscation". Veiw the source of one-file-1f (script) to see how the skeleton C/C++ source file is placed within the shell script. If you have a lot of extra C/C++ type files, that will /* use block remarks */, maybe its time to append a ZIP format file instead of a TEXT format file (that is what its there for). See compile for an example (at the end), or blocks for more details.

Q: why do I need one-file (1f)?
A: oh, you definitely need one-file (1f).
X: if you read this far just for the hell of it, and you are not a programmer or developer, hacker or administator, then you need it in principle, if not for coding. one-file (1f) adheres to the KISS principle of Keep It Simple (Stupid/Silly). So KISS your project with one-file (1f). The simplest form of which is placing everything in a "project directory" and ZIPping it up.

Q: I have no more questions?
A: sweet
X: email, post on project forum, blog about them (and get people to notice them). If they are not too specific to your needs, the solutions can be added to the FAQ.



  The future is so bright, I gotta wear 'shades-1f' ...