first version upgrade

[devspec.git] / devspec.en_US / 1.0.general.txt

posiable => possible\r
integerat => integrat\r
template => template\r
traditional => classical\r
developer =>\r
\r
\r
\r
    dev-spec is not a rule to limit developer, it's an assistant with less\r
limitation. \r
    it provide style doc, and provide auto-utils and template at the same time.\r
        it provide design doc and flow, but only less relative info in design, in\r
order to sync with code, when the developer modify code, it can sync from it,\r
and could use the design info again in next time when it is needed.\r
        it provide dev-flow doc, and it is used with a todolist note as normal. it\r
is just the doc which developer would use it usually.\r
        it provide pkg-structure doc, and also provide util-prog, and simple\r
build paramter file to use it.\r
        it provide webpages guide doc, and also provide .md to html doc util-prog,\r
and webpages sync util-prog, which is referenced from GNU lib.\r
\r
\r
\r
\r
\r
# introduction\r
==============\r
\r
        what's the pkg-builder?\r
        it's a toolset for software build and develop, and provide a develop \r
specific and guide document. \r
    pkg-builder is designed for skeletone-linux building. developer can \r
develop low-level system soft-pkg by it, and do not need to install other \r
software as possible.\r
        pkg-builder uses shell script to write utility programs, it depend external \r
pkgs as less as possible. system building in 'buildroot' need a step of host \r
environment pkg building. by using pkg-builder, it could run system building \r
directly, or just rebuild pkg-builder.\r
    normally, src-pkg build need some advanced soft-pkgs like perl python in\r
desktop linux system. if we need to build a low-level system src-pkg for\r
embedded linux system, we need a cross-compile develop environment on computer.\r
pkg-builder provide utilities writen by shell script, some of the src-pkg can\r
be build in embedded linux system.\r
\r
        what's the devspec?\r
    devspec is a part of pkg-builder. it provide guide document for develop,\r
some of them has a utility program in pkg of 'devutils'. it helps developer to\r
check or generate codes automatically acrroding devspec.\r
    devspec is a thing, that let the developer has the SAME STYLE and METHOD\r
in develop, and uses AUTOMATICAL utility program to ASSIST the devspec. it want \r
to let the pkg-builder to be a CLASSICAL tool, like 'borland c++ builder', or \r
'virsual c++'.\r
\r
        why a src-pkg need the devspec?\r
        devsepc PROVIDE the SAME programming/coding STYLE, and name rules, and so \r
on. it let the different developer write code as a same programer as possible, \r
and other developer can read code easily and clearly.\r
    it provide usage of UTILS in devutils, CHECKING and GENERATING code \r
AUTOMATICALLY. the guide doc would not be a burden for developer as possible.\r
    it provide step guide in developing for software DEVELOPPING LIFE CYCLE.\r
the PROCEDURE of soft-pkg develop can be known by a NEWER. look at the diagram \r
of 'devspec.uml', it shows WHAT PEOPLE will use and operate on a src-pkg. and\r
WHAT THING the people would to do, and the STEP of the thing people would to \r
do.\r
    the FILES generated in develop can be the same as possible, the MEANING and \r
PURPOSE of those file should be defined as same as possible. there are TEMPLATE \r
files for develop in devspec, and use them to generate things by utilities in \r
'devutils' automatically.\r
\r
    devspec is consisted by those part below:\r
\r
@ dev-flow/dev-step guide\r
 # definations for dev-actor, work-task, dev-skill\r
 # defines develop-step diagram. and design diagram files for pkg-builder and\r
   it's sub-pkgs.\r
 # develop manager: dev-task-trace, cooperation, dev-step-trace\r
@ code-style\r
 # code-format\r
 # name-style\r
 # c-cpp-code-format\r
 # sh-code-format\r
@ prog-style: programming style guide. it uses prog-level and prog-elem + \r
  prog-model + prog-lib + traditional-impl to design programs.\r
 # traditional program model/template/sample.\r
 # data-structure and algorithm\r
@ copying lisence\r
@ pkg structure\r
 # version code and it's meaning.\r
 # src-pkg and install-pkg file name format.\r
 # general file types.\r
 # src-pkg file structure.\r
 # install pkg file structure and external dir in system.\r
@ code and executable\r
 # code-manager(file version manager), \r
 # home pages, \r
 # code hosting, \r
 # src/bin public storage pages,\r
 # soft-repo\r
@ template(src-module file comment header, function comment header, src-module\r
  file, program-lang-element, blank project, )\r
 # program element template\r
 # src file template\r
 # project template\r
 # classical implement template\r
\r
\r
\r
# hilight features\r
==================\r
\r
    here list the features for difference from other classical linux-soft-pkg:\r
\r
@ it's automatical thing with less memory remember.\r
\r
@ it defined a develop flow in software developing life cycle.\r
@ develop manage info is putted into the src-pkg. function feature, work task,\r
  task trace, bug trace. some of the will be deleted in publish version, and \r
  traslate content to changelog and TODO.\r
@ simplly home pages for a soft-pkg, and the tools for pages update. it is used\r
  for soft-pkg publish automatically by script programs.\r
@ it defines coding styles, to keep code clear and readable, and use utility\r
  program to generate code automatically, and easy to analyze code by using\r
  'tag-comment'.\r
@ it use template file for code-auto-gen, and code-format. and template for new\r
  src-pkg.\r
@ define directory structure of install pkg, and use .etz file as the binary\r
  publish file. it can install without pkg manager program, and the install\r
  infomation can be used by actual pkg manager program. it defines the public\r
  directories that a software needed, and specified the install path when it is\r
  installing. the pkg manager program record install info, and the public\r
  directories which is needed by a install-pkg.\r
@ define directory of a src-pkg. it append dir of design document, management \r
  document, resource files, and so on. the src-pkg can be used in same dir\r
  structure, and the install-pkg have the same dir struct, it can install by it\r
  self, it's more better then make install. or translate install-pkg to linux \r
  distribution pkg format.\r
\r
\r
\r
# purpose & goal\r
================\r
\r
@ src-pkg developed can be the same style, by same develop flow, same develop\r
  method. it's helpfull for develop cooperation, and code reading.\r
@ integrate automatical tools for developing as possible. the specification\r
  and rules can be used without painstakingly by humen remembering.\r
@ devspec and pkg-builder is designed for system pkg develop and build, in \r
  order to provide a build & develop environment with less program dependence. \r
  it nearly just need shell program and compiler only, build a src-pkg without\r
  make, auto-tools, M4. it integrate flex/bison/gettext/intl/doxygen/texinfo/\r
  pkg-config for developing. some of them are developed by script programs in\r
  devutils, and some of them are in the plan.\r
  especially, it is used for the pkgs of 'skeletone-linux', and the src-pkgs in \r
  this skeletone.\r
@ it uses c/c++, and shell script as the default programming language. and \r
  maybe use languages like 'vala', for modulization of c-language.\r
@ for pure application programs, there are many build tools. devspec and \r
  pkg-builder can not cover various range of applications.\r
@ textilization. use editable text file as more as possible. it's easy to edit,\r
  and can be read without special utility programs. easy to analysis problems\r
  when error occurs.\r
\r
\r
\r
# scrope & misc\r
===============\r
\r
@ mainly for system low-level src-pkgs, espacially for 'skeletone-linux'.\r
@ the lisence of 'skeletone-linux' src-pkg to be developed would be MIT as \r
  possible. others, look at the document of 'copying-lisence'.\r
@ main dependence of external src-pkgs is gcc, and shell program, and few \r
  binary programs. the binary pkgs it needed, will be improved by shell script \r
  as possible. the concept of shell program is not only shell script \r
  interpreter, it include command set for a shell environment.\r
@ this document is mainly for suggest guide, and the rules must be kept in \r
  'skeletone-linux' pkgs, to be a suggest guide beyound 'skeletone-linux'.\r
@ \r
\r
\r
\r
# reading guide for devspec\r
===========================\r
\r
@ dev-step\r
    it defined a suggest develop step.\r
    look at the document of 'project-develop-step'.\r
    view the uml diagram document in dir of 'dev-step-diagrams' by umberello.\r
\r
@ the defination of dev actor, and work task\r
    look at the document of 'dev-actor-task' 'develop-step-diagrams'.\r
    view the uml diagram document in dir of 'dev-step-diagrams' by umberello.\r
\r
@ project manager(design feature list, task, cooperation, dev-step-trace)\r
    the feature of a soft-pkg is not recorded in src-pkg. but it's usefull for\r
user and developer. it uses changelog for feature record when it is published.\r
but sometimes, it need record the features which has not been developed.\r
    orgnize a task to develop one of the feature in feature list, and provide\r
develop step trace, to see the status of feature developing.\r
    submit a bug, and launch a task to fix it.\r
        when the soft-pkg is published, keep feature list, output changelog/news by \r
manager info, and delete develop manager doc.\r
    look at the document of 'develop-work-task'.\r
\r
@ programming styles\r
    look at the document of 'rules'.\r
\r
# code-format\r
    code format or code style defination.\r
    look at the document of 'code-format', 'name-style', 'c-cpp-code-format', \r
        'sh-code-format'.\r
\r
# name-style\r
    it's a part of code-style.\r
    look at the document of 'name-style'.\r
\r
@ copying and lisence\r
    it's depend on the type and purpose of src-pkgs would be developed. it \r
defines lisence type of different src-pkg type in a operating system.\r
        look at the document of 'copying-lisence'.\r
\r
@ pkg structure\r
# name and directory structure of a pkg\r
    define install pkg name format, so that pkg info can be dispatched from\r
install pkg file name. \r
    the directory structure for src-pkg is defined. use project template in\r
developing.\r
        directory of install-pkg is defined, a soft-pkg can be installed in various\r
operation systems.\r
    look at the document of 'srcpkg-general-doc-files', \r
'instpkg-general-doc-files'.\r
\r
# version code\r
    define the meaning of version code, and use utility program to increas \r
version code when a src-pkg is published.\r
    look at the document of 'version-code', \r
\r
@ code-manager\r
# file version manager, \r
# code repo, \r
    version manager program usage document, for src-pkgs and install-pkgs.\r
    look at the document of 'git-client-usage'.\r
    look at the document of 'code-repo-usage'.\r
\r
# home pages, \r
# src/bin public storage pages,\r
    it provide guide document for code hosting, and how to use utilities in \r
soft-pkg of 'devutils', to create/update/publish web pages.\r
    it provide guide document for a developer for things beyound coding.\r
    look at the document of 'code-hosting'.\r
\r
@ template(src-module file comment header, function comment header, src-module \r
  file, program-lang-element, blank project, )\r
    template file is used for code-gen and code-fmt. use utility program, or\r
used as a guide document for coding.\r
    look at the document of 'sample-prj-and-code-tmpl'.\r
\r
\r
\r
\r
\r