WebSVN – SvarDOS – Diff – /website/help/help-en.amb


AMB1
index.ama
kpkg.amaD0.network.amacàn
contact.amaC±°pkgfmt.amaFïTpkgrules.amab!Ùlicense.ama;*@V?meaning.ama{-mUfreedos.ama1M
[Âhistory.amaO;Þ¥Rtodo.ama-B2'Ù8086.ama_J÷
ÝtitleVX!G
                            %h*** SVARDOS HELP ***
 
This help documentation is a work-in-progress thing. For the time being it
provides only very limited content. (wanna help building it? get in touch with
us on the SvarDOS %lcontact.ama:mailing list%t!)
 
=== Chapters =================================================================
 
 * %lpkg.ama:Packages management (install/remove/update software)
 * %lnetwork.ama:Networking
 
 * %lfreedos.ama:SvarDOS vs FreeDOS: what is the story?
 * %ltodo.ama:The project's "TODO" list
 * %lcontact.ama:How do I get in touch with the SvarDOS community?
 
 * %lhistory.ama:SvarDOS origins
 * %lmeaning.ama:What does "Svarog" mean?
 * %l8086.ama:8086 compatibility list
 
==============================================================================
 
%hSvarDOS packages management
 
To install or remove software on your SvarDOS system, use the "pkg" command.
pkg is a package manager to allow installing new software from SvarDOS
packages and removing exising software from the system. To learn about exact
pkg usage, type pkg /? in the SvarDOS command line shell.
 
You may obtain many SvarDOS packages from the SvarDOS web homepage at
<http://svardos.osdn.io>. If your system is connected to the internet, then
you may also use the SvarDOS "pkgnet" command. pkgnet is a network tool that
makes it easy to search for SvarDOS packages in the SvarDOS repository and
download them right away. Type pkgnet /? in the SvarDOS command line shell to
learn about exact pkgnet usage.
 
See also:
 * %lpkgfmt.ama:The technical format of a SvarDOS package
 * %lpkgrules.ama:Packages inclusion rules
 
%hNetworking
 
For enabling network connectivity you first need to know what kind of network
adapter you have, and obtain a suitable packet driver for it. The "crynwr"
package contains lots of packet drivers for a variety of network adapters.
There is also a packet driver for Intel Pro cards in the e1000pkt package, and
a driver for AMD PC-NET cards in the pcntpk package.
 
You need to get the packet driver for your card onto the machine, and load it.
Then, you should be able to access the internet and get anything else you need
using wget, htget, gopherus and other network-enabled applications.
 
Note that packet drivers are mostly available for old-ish interfaces. If you
have some modern ethernet card, then there might not be a packet driver
available for it.
 
%hFILE SHARING
 
Perhaps these links could provide some pointers:
<http://wiki.freedos.org/wiki/index.php/Networking_FreeDOS_-_MS_Client>
<https://www.lazybrowndog.net/freedos/virtualbox/?page_id=374>
 
There is also EtherDFS, which is a very lightweight and easy solution for
file-sharing between DOS and Linux (but it does require a Linux PC and some
basic understanding of how Linux works):
<http://etherdfs.sourceforge.net/>
 
%hVIRTUALBOX - PACKET DRIVER
 
VirtualBox is able to emulate an AMD PC-NET NIC (you need to make sure of that
in the configuration of your VM, VirtualBox calls it "PCnet-FAST III" and it
should be set to "NAT"). Then, in SvarDOS you have to install the pcntpk.zip
package - you don't even need to download it, it's already present on the
installation image so it should be as simple as that:
 
pkg install a:\pcntpk.zip
 
Finally, load it as such:
 
C:\DRIVERS\PCNTPK\PCNTPK INT=0x60
 
...and that's it. From now on, you should be able to search through the
available online packages and install extra software, for example:
 
pkgnet pull gopherus
pkg install gopherus.zip
 
(gopherus is a gopher browser)
 
To search through the list of available packages in the online repository, use
that:
 
pkgnet search your_search_term
 
%hHow do I get in touch with the project's community?
 
The recommended way to contact the SvarDOS community is through the project's
mailing list: <https://lists.osdn.me/mailman/listinfo/svardos-users>
 
The project's web homepage is <http://svardos.osdn.io>
 
Package files provide an easy way to manage software on SvarDOS. These
packages must adhere to a strict convention so they can be handled properly
by the SvarDOS package manager.
 
 
%hPackage filenames
 
Packages names must follow some basic rules. They shall be max. 8 letters long
(but should not be too short either, since a 1 or 2-letters package name might
be confusing), and must not be composed of characters other than a-b, 0-9 and
'_'. This for backward compatibility with short file names (8+3) and ISO 9660
file systems (used on CDROMs). The package filename is always followed by the
.ZIP extension.
 
 
%hPackage files
 
SvarDOS uses ZIP files as its package file format. This format has been chosen
because ZIP files under DOS have become the de facto way to distribute
collections of files. Also, the ZIP file format is well documented, well
supported, and in the public domain.
 
Here below is the recommended command line that can be used to create a
package for a program named EXAMPLE using info-zip:
 
  zip -9rkDX EXAMPLE.ZIP subdir1 subdir2 ... subdirN
 
If you are using 7za to create your packages, then use this:
 
  7za a -mm=deflate -mx=9 -tzip EXAMPLE.ZIP subdir1 subdir2 ... subdirN
 
 
%hPackage directory structure
 
The directory structure of a package depends on the type of packages.
For "core" packages, we have this:
 
  APPINFO            Put the program's LSM file here
  BIN                Binaries, such as exe and com files
  DOC\PKGNAME        Package documentation
  HELP               Used ONLY by the "help" package
  NLS\PKGNAME        Localizations (NLS language files) of the package
  SOURCE\PKGNAME     The source code (optional)
 
Non-core packages use a slightly different directory organization. For
example, if we were to consider a package FOO, we might end up with the
following structure:
 
  APPINFO\FOO.LSM    Package meta file for the FOO program
  PROGS\FOO\FOO.EXE  The program's executable
  PROGS\FOO\FOO.TXT  Some documentation
  PROGS\FOO\FILE.DAT Data file used by the FOO program
  SOURCE\FOO\*       here would be stored the foo's source code (optional)
 
Note the 'PROGS' directory above. This is a category to which the package
belong. The package installer might change this directory at install time,
depending on the user's preferences. Possible categories are listed below:
 
Category | Description
DEVEL    | Development tools (mostly compilers)
DRIVERS  | Drivers
GAMES    | Games
PROGS    | User programs, tools...
 
Note: "DOC", "NLS", "BIN" and "HELP" directories are strictly reserved to
      CORE packages.
 
 
%hLSM meta-data files
 
Every package MUST contain an LSM file in its "APPINFO" directory. This LSM
file is a text file that contains basic information about the package. Its
format is very simple, it must contain at least two lines:
 
  version: x.y.z
  description: package description
 
Any other lines are ignored by the SvarDOS package manager.
 
 
%hPackage versions
 
The version present in the LSM file is meant to reflect the version of the
packaged software, but it may happen that a package needs to be changed to
fix a strictly packaging-related issue (for example a forgotten documentation
file or a recompilation of the binary using a better set of flags...). In such
case, the version of the software does not change, but the version of the
package itself needs to change so users know something changed. That's where
"SvarDOS revisions" come in. A version string is basically following such
format:
 
  UPSTREAM_VER[+SVARREV]
 
UPSTREAM_VER is the exact version string advertised by the software. It may
be pretty much anything. This upstream version may be optionally followed by a
plus sign and the SvarDOS revision. In the event that the upstream version
already contains a plus sign, then SvarDOS revision is delimited with a tilde.
 
The SvarDOS revision starts at 0 and increments each time that the given
upstream revision is repackaged. The SvarDOS revision restarts whenever the
upstream version changes. The SvarDOS revision of 0 is always hidden.
 
Examples:
 
FDISK 1.54      <- originally packaged version
FDISK 1.54+1    <- package has been changed, but not the upstream version
FDISK 1.55      <- upstream version increased, so SvarDOS rev restarts
FDISK 1.55+1    <- new version of the package, but still contains FDISK 1.55
FDISK 1.55+2    <- another new version of the package, etc
 
                     %h*** Packages inclusion rules ***
 
SvarDOS is a DOS distribution that comes with plenty of third-party packages.
With time, packages get updated and new packages are being added. However,
SvarDOS is not a shareware distribution CD, nor it is a "warez" production of
any kind. Every software that is distributed within SvarDOS must comply to a
few common sense rules, as listed below.
 
%hObjective usefulness
 
The distributed software must be useful. There is no point in distributing
hundreds of "Hello World" programs for example. The software must be useable
as a finished product and provide some features that are proven to be seeked
by at least a subset of the user base. Games are considered useful, as long as
they fulfill their goal of providing actual distraction.
 
%hReasonable quality
 
The packaged program must exhibit traits of reasonable quality. This means
that it should have a deterministic behavior, and be free of undesirable
side-effects to the user's computer (not crashing, freezing, resulting in
unexpected loss of data, etc). It should also provide clear, non-ambiguous
instructions to the user about how the program is meant to be used.
 
%hFree (no cost)
 
The program must be free - that is, available at no financial cost. It doesn't
have to comply to an OSI-approved license or be open-source (even if that
would be preferred), but at the very least it must be free for personal,
non-commercial use. This includes "Freeware", "postcardware", etc. "Shareware"
is acceptable, too, as long as the shareware version of the program fullfills
the conditions of usefulness, quality and allows repackaged distribution.
 
%hDistribution allowed
 
The program must allow distribution without restrictions, and must not forbid
being redistributed in a re-packaged form.
 
 
%!CORE EXCEPTIONS
 
While the above rules are valid for all third-party packages that may be
distributed with SvarDOS, it does NOT apply to the "CORE" packages that contain
the operating system itself. SvarDOS being a free (as in "libre") operating
system, all CORE packages must comply to a libre-like license - be it GPL, BSD,
MIT, public domain, or anything that allows for unrestricted distribution,
provides source code and allows to modify it freely.
 
%hSvarDOS licensing
 
SvarDOS is a DOS distribution made of many different software bricks, hence a
single license can hardly be applied to all. However, the CORE system (that
is the SvarDOS installer, bootable images and all CORE packages) is carefully
assembled from software that is "free" (as in "Freedom"), ie. that grants the 3
basic FOSS liberties: freedom to use, modify, and redistribute. This includes,
but is not necessarily limited to, software released under following licenses:
GNU GPLv2, GNU GPLv3, BSD, MIT, EUPL and Public domain.
 
Note that, while the above applies to the core of the SvarDOS distribution, it
does not cover all extra packages. Additional software packages may or may not
be FOSS, they are only guaranteed to be "gratis for non-commercial use".
 
Read more: %lpkgrules.ama:Packages inclusion rules
 
%hWhat does "Svarog" mean?
 
The "Svar" in SvarDOS refers to "Svarog". SvarDOS is the successor of the
Svarog86 and Svarog386 distributions.
 
Excerpt from Wikipedia, the free encyclopedia:
 
 Svarog is a Slavic deity (...) identified with Hephaestus, the god of the
 blacksmith in ancient Greek religion (...), some researchers conclude that
 Svarog is the Slavic god of celestial fire and of blacksmithing.
 
 The only mention of Svarog comes from the Hypatian Codex, a 15th-century
 compilation of several much older documents from the Ipatiev Monastery in
 Russia. (...) The complete passage, reconstructed from several manuscripts,
 translates as follows:
 
 "(Then) began his reign Feosta (Hephaestus), whom the Egyptians called Svarog
  ... during his rule, from the heavens fell the smith's prongs and weapons
  were forged for the first time; before that, (people) fought with clubs and
  stones."
 
        %h*** Why would I want to use SvarDOS instead of FreeDOS? ***
 
The FreeDOS project is a free, open-source operating system that aims to be
100%% compatible with MS-DOS. And it is awesome. So why would I want to use
SvarDOS instead?
 
%hLong release cycles
 
The FreeDOS project began 29 June 1994. Version 1.0 came around in 2006.
Version 1.1 has been released in 2012, and the version 1.2 followed in
December 2016. This translates roughly to a 5-years release cycle. Granted,
the DOS scene is not as active as it used to be, but still, many things happen
during a few years. Such version-centric approach also requires users to
perform full-system upgrades every now and then.
 
SvarDOS is very different in this regard: there are no versions at all.
Whenever a new program is included into or updated within the distribution, it
becomes immediately available through the SvarDOS reposoitory and may be
pulled either through the SvarDOS website or SvarDOS' pkgnet tool. Already
installed systems can be easily kept up-to-date using the distribution's
package manager.
 
%hConstraints of legal nature
 
The FreeDOS project mimicks a proprietary operating system, with all its APIs
and peculiarities. For this reason, the project always had to be extremely
careful about what can and what cannot be included within the FreeDOS
distribution. As a result, only "free software" (as in freedom, think GPL,
BSD, and so on) can make its way into the official distribution. While such
cautious approach is sane and legally safe, it is far from practical for
users. Allowing exclusively free software means that a high number of useful
programs, tools and games are left behind. For example "freeware" tools (as in
"gratis but no source included") are a no-go. Even open-source programs can be
rejected, if they do not clearly state that they comply with an OSI-approved
license.
 
SvarDOS, on the other hand, is much more liberal about including packages.
Basically, anything that is objectively useful, of reasonable quality,
free/gratis and can be legally distributed in the form of a package, can be
included in SvarDOS. The only exception is for the "core" system (ie. the
operating system itself), which must be based exclusively on free/libre
software. Read more about %lpkgrules.ama:SvarDOS package inclusion rules%t.
 
%hFreeDOS included!
 
It must be noted, that altough the goals of SvarDOS and FreeDOS may be
slightly different, SvarDOS wouldn't exist without FreeDOS. Indeed, SvarDOS
uses the excellent FreeDOS kernel, as well as a few other utilities borrowed
from the FreeDOS ecosystem.
 
Read also: %lhistory.ama:SvarDOS history
 
%hSvarDOS origins (history from the point of view of its creator)
 
Mateusz Viste says:
 
In the years 2005-2015 I used to perform packaging work for the FreeDOS
project. I wasn't pleased with the packaging tool that FreeDOS used back then
(FDPKG), so in 2012 I started working on a new package manager, with network
support, automatic updates, etc - I named it FDNPKG. Later I also devised a
scripted way of generating an "always up to date" FreeDOS CD that I
unimaginatively called "all_cd.iso". This CD included FDNPKG and all the
FreeDOS packages available at the given moment.
 
I still wasn't satisfied with how FreeDOS clings to its notion of "releases"
and that it cannot include some software because of licensing issues, so in
2016 I decided to create my own distribution, that I called Svarog386 (there
was also a Svarog86 project that I had created a couple months earlier,
dedicated to 8086 machines). Svarog386 naturally relied on the FreeDOS kernel
and used the FDNPKG package manager.
 
Then, in 2021, I found it increasingly annoying to look after two separate
distributions. Over time, FDNPKG also became a huge piece of protected mode
code, and although it was magnificent code, I was no longer happy with it: too
many features, too much data processing, too much memory required... In a
word: too much fluff. I longed for something simpler, that would do perhaps
less, but with more transparency towards the user - and something that would
work in real mode with not much RAM, so it could run even on ancient 8086
machines.
 
The result of these thoughts was SvarDOS: a distribution that replaced both
Svarog86 and Svarog386, and that came with its own package manager - a much
simpler (and in my opinion much more elegant) tool than FDNPKG.
 
%hSvarDOS: The project's TODO list
 
* Replace the default (FreeDOS) edit with a smaller alternative (?) that is:
  - TINY (a dozen of KiBs or so)
  - relatively simple: no need for advanced text editing features, just enough
    to comfortably edit small (<64K) configuration files
  - 8086-compatible and have modest memory requirements
  - multi-lang (kitten library)
  - capable of (limited) copy/pasting between two files
 
* replace FreeCOM by SvarCOM
 
* improve installer so user can choose the target disk
 
* COUNTRY settings shall be configurable by localcfg (and user should be
  able to define local preferences through an easy-to-use wizard during
  install time)
 
* out-of-the box networking support:
 - requires shipping lots of packet drivers with SvarDOS... Should CRYNWR be
   part of the install set? Or only selected, most popular drivers? Or maybe
   this could be provided as a "supplemental" floppy disk?
 - user should be asked for its NIC model at install time
 - installer could also ask for a basic DHCP / static configuration
 
* install.com - MBR changes could be done by the installer itself instead of
  system()-calling fdisk
 
* help - write more useful content!
  - basic DOS commands (directories, copy/rename/delete files, etc)
  - common configuration files (autoexec, config.sys, pkg.cfg, wattcp.cfg..)
  - networking guide
  - memory management basics
  - ...
 
* test new versions of software and update packages accordingly. special care
  must be taken for core things: kernel, command.com, fdisk, himemx...
 
* add new, useful software to the SvarDOS repository (see the %lpkgrules.ama:rules%t)
 
* further NLS support, improvements of existing translations and adding new
  languages -> would be nice to have some kind of web interface for submitting
  and reviewing translations
 
* all user-facing CORE packages should be NLS-aware (translatable)
 
* possibly plenty of other things
 
 
                        =============================
                          %hWanna help? %lcontact.ama:Get in touch!
                        =============================
 
%h8086 compatibility
 
This page presents the 8086-compatibility status of each SvarDOS "CORE"
package.
 
%bPACKAGE     VERSION   EXECUTABLE BSUM  8086 ok?*   Checked on
amb        20201223      amb.com A11A     yes      2022-01-30
attrib          2.1   attrib.com 2C15     yes      2022-01-30
chkdsk   0.9.2 beta   chkdsk.exe E2A9     yes      2022-01-30
choice          4.4   choice.exe 8311     yes      2022-01-30
command  0.84 pre 2  command.com E64E     yes      2022-01-30  01)
cpidos          3.0         none   -       -       2022-01-30
debug          1.25    debug.com 2E6B     yes      2022-01-31
debug          1.25   debugx.com EA59     yes      2022-01-31
deltree  1.02g.mrlg  deltree.com E20D      no      2022-01-30  02)
deltree       1.02g  deltree.com AB16     yes      2022-01-31  03)
devload        3.25  devload.com B91B     yes      2022-01-30
diskcopy  beta 0.95 diskcopy.exe 3558     yes      2022-01-30
display       0.13b  display.exe 5903     yes      2022-01-30
dosfsck       2.11c  dosfsck.exe 1CB8     yes      2022-01-30
edit           0.9a     edit.exe 8F1A     yes      2022-01-30
fc             3.03       fc.exe E718     yes      2022-01-30
fdapm     2009sep11    fdapm.com A74A     yes      2022-01-30
fdapm     2009sep11 idledpms.com C8BD     yes      2022-01-30
fdisk         1.3.4    fdisk.exe F098      no      2022-01-30  04)
fdisk         1.3.4    fdisk.exe 98BF     yes      2022-01-31  05)
find       3.0a LFN     find.com A9DA     yes      2022-01-30
format        0.91v   format.exe F11E     yes      2022-01-30
help       20220124         none   -       -       2022-01-30
himemx         3.34   himemx.exe C8E6     yes      2022-01-30  06)
kernel         2042      sys.com BF43     yes      2022-01-30
kernel         2042   kernel.sys A9B2     yes      2022-01-30
keyb           2.01     keyb.exe 945C     yes      2022-01-30
keyb_lay        3.1         none   -       -       2022-01-30
label       1.4b.ea    label.exe 1F5D     yes      2022-01-30
localcfg       0.90 localcfg.com E424     yes      2022-01-30
mem           1.11r      mem.exe 2BB8     yes      2022-01-30  07)
mode     2015-11-25     mode.com BA1E     yes      2022-01-30
more            4.3     more.exe 729B     yes      2022-01-30
move           3.3a     move.exe D3E4     yes      2022-01-30
pkg        20210212      pkg.exe 9FAB     yes      2022-01-30
pkgnet     20220119   pkgnet.exe 3D2F     yes      2022-01-30
shsucdx        3.05  shcdx86.com 0A74     yes      2022-01-30
shsucdx        3.05  shsucdx.com E5A5     yes      2022-01-30  08)
sort          1.5.1     sort.exe 21C2     yes      2022-01-30
tree          3.7.2     tree.com 2370     yes      2022-01-30
(pcntpk)      03.10   pcntpk.com 38C7     yes      2022-01-30
(udvd2)   30-Apr-13    udvd2.sys D3AB     yes      2022-01-30  09)
 
* Executable does its normal job or exits gracefully with a hint.
 
Notes:
01) also has localized versions from cmd-de.com (German) to cmd-tr.com
    (Turkish)
02) pce-ibmpc: undefined operation [C1 04] -> uncompressing with UPX
    made it work
03) replaced BSUM E20D file; used UPX --8086 option
04) pce-ibmpc: undefined operation [C1 e1] -> needed a full rebuild
05) replaced BSUM F098 file; no -1 option for TC++; used UPX --8086 option
06) exits with "At least a 80386 is required."
07) under pce-ibmpc reports 1,024K of conventional memory, but 0K free
08) exits with "Must have at least a 386."
09) exits with "No 386+ CPU; UDVD2 not loaded!"
 
------------------------------------------------------------------------------
Article by Robert Riebisch
SVARDOS HELP SYSTEM ver 20220204
 
Subversion Repositories SvarDOS

(root)/website/help/help-en.amb @ 621 – Rev 618 → 621
