Tämä on kotisivu / dokumentaatio Kromi OS Shellille. Jos olet CrOS laitteet juuri nyt, sinun pitäisi pystyä käynnistämään crosh painamalla Ctrl + Alt + T. Jos et ole CrOS, niin todennäköisesti, että ei tee mitään hyödyllistä:).

aja vain help saadaksesi tietoa käytettävissä olevista komennoista ja löytääksesi lisää.

voit myös käyttää välilehden täydennystä löytääksesi nopeasti olemassa olevat komennot.

It ’ s an adventure!

Kromi-käyttöjärjestelmän kehittäjille

Tämä osio on tarkoitettu Kromi-käyttöjärjestelmään murtautuville ihmisille, erityisesti silloin, kun heidän on muokattava / laajennettava crosh-käyttöjärjestelmää.

Turvavaroitus

älä asenna uusia moduuleja ilman täydellistä turvakatselmusta. Kaikki croshin lataamat turvattomat koodit ovat suoraan ihmisten saatavilla verified-tilassa. Se on helppo hyökkäysvektori ajaa mielivaltaista koodia ja sotkea käyttäjän tilaa. Emme halua heikentää Crosin turvallisuutta!

Jos etsit arvostelijoita, katso./ Omistajien tiedosto.

missä tiedostot elävät

Crosh on siirtymässä Shellistä ruosteeseen. Crosh aloittaa suorittamisen src/main.rs: stä, mutta useimmat komennot toteutetaan omana alimodulina jostakin korkean tason moduulista (esim. base tai dev).

tärkein crosh skripti sisältää crosh-ydinlogiikan periytyvän toteutuksen muiden vanhojen funktioiden asuessa moduulihakemistoissa. Croshin vanha versio on asennettu laitteeseen nimellä crosh.sh.

Source repot

moduulit, jotka ovat erityisiä kartongille tai erittäin erityisiä paketille, tulisi yleensä elää kyseisen kartongin ja / tai paketin kanssa. Niiden toimintojen osalta, jotka ovat aina käytettävissä kaikissa Cros-laitteissa, kyseinen koodi on säilytettävä tässä repossa.

Jos olet epävarma, kysy [email protected].

uusien komentojen lisääminen

määrää ensin, mitä toteutusstrategiaa uusi komento käyttää. Strategian valinnassa auttaa tietää, mitä oikeuksia ja oikeuksia tarvitaan. Strategia mielessä, Tutustu eri esimerkkejä alla.

Komentosuunnittelu

crosh-komentotulkki toimii samassa ympäristössä kuin selain (sama käyttäjä / ryhmä, samat Linux-nimiavaruudet jne…). Joten kaikki crosh: ssa ajamasi työkalut tai hankkimasi TIEDOT täytyy olla chronos käyttäjän saatavilla.

haluamme kuitenkin harvoin, että crosh todella suorittaa työkaluja suoraan. Sen sijaan sinun pitäisi lisätä D-Bus-kutsupalautuksia debugd-taustaprosessiin ja lähettää kaikki pyynnöt siihen. Voimme paremmin hallita pääsyä debugd ja lukita työkalut alas. Sitten ainoa logiikka, joka on olemassa crosh on D-Bus IPC puhelu ja sitten näyttää lähtö näistä ohjelmista. Debugd-keskustelu ei kuulu tähän, joten tarkista sen sijaan debugd-Hakemisto.

Examples

examples implementations:

• D-Bus method wrapper (debugd): base::verify_ro
  Käytä tätä, kun D-Bus API on jo suunnitteilla tai crosh: lta puuttuu tarvittavat käyttöoikeudet tai ominaisuudet.
• External binary wrapper: base::ccd_pass
  Käytä tätä, kun on jo olemassa komentorivityökalu, joka toteuttaa komennon, joka toimii ajettaessa nimellä chronos croshin ominaisuuksilla.
• ruosteella kirjoitettu komento: pohja::arc
  Tämä soveltuu parhaiten tapauksiin, joissa lisäominaisuuksia ei tarvita eikä erillisen komentorivityökalun käyttö ole perusteltua.

alla on näytteen työnkulku uuden komennon kirjoittamista varten.

moduulin asetukset

valitse sopiva moduuli, johon komento kuuluu. Dev-tilan komennoissa tämä on dev, useimmat muut komennot kuuluvat base. Tässä esimerkissä käytetään moduulina base, mutta samat vaiheet pätevät edelleen muissakin tapauksissa.

valitse sitten komennon nimi, Luo alimoduuli, jolla on kyseinen nimi, ja rekisteröi se ylämoduuliin. Tässä esimerkissä komento on verify_ro, joten Uusi lähdekooditiedosto on src/base/verify_ro.rs ja src/base/mod.rs:

ensin on tuotava alimodule:

mod verify_ro;

toinen rekisterifunktio (luodaan alla) tarvitsee kantamoduulin rekisterifunktion src/base/mod.rs:

nyt src/base/verify_ro.rs lähdekooditiedosto on valmis kirjoitettavaksi. Aloita tästä minimaalisesta lähdekooditiedostosta ja varmista, että crosh kokoaa cargo build:

use crate::dispatcher::Dispatcher;pub fn register(dispatcher: &mut Dispatcher) { dispatcher.register_command( Command::new( "verify_ro".to_string(), "TODO put usage here".to_string(), "TODO put description here".to_string(), ) .set_command_callback(Some(execute_verify_ro)), );}fn execute_verify_ro(_cmd: &Command, args: &Arguments) -> Result<(), dispatcher::Error> { unimplemented!();}

komennon toteutus

tämä olettaa yllä olevien ohjeiden olevan jo valmiit.

koska etuoikeutettuja operaatioita ei voi suorittaa Crosh: lla (vaan ne tulisi toteuttaa debugd: ssä tai missä tahansa muualla), alla olevassa esimerkissä keskitytään erityisesti D-Bus: iin ja oletetaan, että on olemassa olemassa oleva D-Bus-menetelmä, joka on kutsuttava uudesta Crosh-komennosta.

huomaa, että debugd: n D-Bus-liitännässä on jo Dev-rust/system_api: n kautta luodut Ruostesidokset ja D-Bus-liitännät voidaan tuoda:

use dbus::blocking::Connection;use system_api::client::OrgChromiumDebugd;

Jos haluat selata luotujen sidosten lähdekoodia, tarkista build_packages-ajon jälkeen seuraava polku:

/build/${BOARD}/usr/lib/cros_rust_registry/registry/system_api-*/src/bindings/client/

komentototeutuksen sisällä on alustettava D-Bus-yhteys. Tässä esimerkissä käytetään estoyhteyttä.

let connection = Connection::new_system().map_err(|err| { error!("ERROR: Failed to get D-Bus connection: {}", err); dispatcher::Error::CommandReturnedError})?;

väyläyhteyden avulla voidaan sitten saada liitäntä haluttuun palveluun, joka on tässä tapauksessa debugd:

let conn_path = connection.with_proxy( "org.chromium.debugd", "/org/chromium/debugd", DEFAULT_DBUS_TIMEOUT,);

muu menetelmäkutsu käyttää sitä, että tuotu ominaisuus system_api::client::OrgChromiumDebugd toteutetaan conn_path joten D-Bus-menetelmiin kartoittavia jäsenfunktioita voidaan kutsua conn_path. Esimerkiksi:

conn_path .update_and_verify_fwon_usb_stop(handle) .map_err(|err| { println!("ERROR: Got unexpected result: {}", err); dispatcher::Error::CommandReturnedError })?;

Tämä kattaa perusasiat. Jos katsot todellista lähdekoodia baselle::verify_ro, se tarjoaa monimutkaisemman esimerkin start method call, valvoja, ja stop method call.

komennon Ohje

oletusmerkkijonot on kansoitettu komennon nimen, käyttömerkkijonon, kuvausmerkkijonon sekä lähettäjän API: n kautta rekisteröityjen vaihtoehtojen tai lippujen avulla.

vaihtoehtoisesti komennon rekisteröinnissä voidaan asettaa ohjeen takaisinkutsu mukautetun logiikan suorittamiseksi, kuten binäärin ohjevalinnan kutsuminen. Esimerkiksi:

const EXECUTABLE: &str = "/usr/bin/vmc";pub fn register(dispatcher: &mut Dispatcher) { dispatcher.register_command( Command::new("vmc".to_string(), "".to_string(), "".to_string()) .set_command_callback(Some(execute_vmc)) .set_help_callback(vmc_help), );}fn vmc_help(_cmd: &Command, w: &mut dyn Write, _level: usize) { let mut sub = process::Command::new(EXECUTABLE) .arg("--help") .stdout(Stdio::piped()) .spawn() .unwrap(); if copy(&mut sub.stdout.take().unwrap(), w).is_err() { panic!(); } if sub.wait().is_err() { panic!(); }}

Deprecating Commands

Jos haluat korvata crosh-komennon jollain muulla käyttöliittymällä (kuten chrome:/ / page), ja haluat deprecatoida komennon sulavasti jättämällä ystävällisen viestin, jos ihmiset yrittävät käyttää sitä, tässä lomake.

# Set the vars to pass the unittests ...USAGE_storage_status=''HELP_storage_status=''# ... then unset them to hide the command from "help" output.unset USAGE_storage_status HELP_storage_statuscmd_storage_status() ( # TODO: Delete this after the R## release branch. echo "Removed. See storage_info section in chrome://system")

varmista, että lisäät TODO-kommentin, jotta ihmiset tietävät tulevaisuudessa, milloin on OK siivota se.

testaus

iteratiivinen kehitys

voit ajaa ./crosh työpöytäjärjestelmälläsi saadaksesi näytetulkin. Voit nopeasti testata perusvuorovaikutukset (kuten argumentin jäsennys) täällä, tai tarkistaa ohjetuloksen. Sinulla ei ole pääsyä Cros-palveluihin, joihin monet crosh-komennot odottavat puhuvansa (D-Bus: n kautta), joten nämä komennot epäonnistuvat.

Jos haluat ladata dev-moodimoduuleja, voit käyttää ./crosh --dev. Se lataa vain paikallisia moduuleja (./dev.d/), joten jos moduulisi asuu muualla, voit kopioida sen täältä väliaikaisesti.

vastaavasti, jos haluat ladata irrotettavia laitemoduuleja, voit käyttää ./crosh --removable.

Unittestit

yksikkötestien suorittamiseen joko kutsutaan cargo test --workspace crosh-kansioon tai ajetaan emege-${BOARD} crosh && FEATURES=test emerge-${BOARD}

./run_tests.sh legacy unittest runner suorittaa tukun perustyylin ja soundtarkistuksen. Vertaa komentotulkin koodin muutoksia!

Tulevaisuustyö

kenen tahansa pitäisi rohkeasti tarttua näihin ideoihin ja yrittää toteuttaa niitä :).

• Siirrä kaikki paikallaan toteutetut jäljellä olevat komennot debugd-kutsuihin, jotta ne voidaan tehdä D-Bus: n kautta.
• aja crosh itse rajoitetulla hiekkalaatikolla (nimiavaruudet/seccomp / etc…). Kun kaikki komennot tehdään IPC: n kautta, privs: ää ei tarvitse pitää. Saattaa tehdä sen riippuvaiseksi dev-tilasta, joten emme riko shell.
• siirrä ylimääräiset legacy shell-komennot Rustille. Tämä voidaan tehdä myös samaan aikaan, kun siirretään komento debugd: hen.

Legacy Crosh Documentation

Crosh kirjoitettiin alun perin komentotulkilla. Kirjoitushetkellä monet komennot ovat edelleen kuoressa, eikä niitä ole vielä siirretty Rust croshille. Tämä dokumentaatio säilytetään täällä näiden komentojen ylläpitoa varten.

Komentorajapinta

jokaiselle komennolle määritellään kaksi muuttujaa ja yksi funktio. Uusia komentoja ei tarvitse rekisteröidä mihinkään, sillä crosh tarkastaa oman ajonaikaisen ympäristönsä löytääkseen ne.

näin rekisteröit uuden foo komennon.

# A short description of arguments that this command accepts.USAGE_foo='<some args>'HELP_foo=' Extended description of this command.'# Not required, but lets crosh detect if the foo program is available in the# current system (e.g. the package is not installed on all devices). If it# isn't available, crosh will automatically display an error message and never# call cmd_foo.EXEC_foo='/full/path/to/program'cmd_foo() ( # Implementation for the foo command. # You should validate $# and "$@" and process them first. # For invalid args, call the help function with an error message # before returning non-zero. ...foo code goes here!...)

katso alla olevasta suunnitteluosiosta tarkemmin, mitä ja miten uusi komento jäsennetään.

Komentoapu

Jos crosh-komentosi vain kutsuu ulkopuolista ohjelmaa suorittamaan käsittelyn, ja kyseinen ohjelma tarjoaa jo käyttötietoja, et luultavasti halua joutua toistamaan asioita. Voit käsitellä tätä skenaariota määrittelemällä help_foo funktion, joka tekee vastaavan kutsun.

# Set the help string so crosh can discover us automatically.HELP_foo=''cmd_foo() ( ...)help_foo() ( /some/command --help)

huomaa, että asetamme edelleen HELP_foo. Tätä tarvitaan, jotta crosh voi löytää meidät automaattisesti ja näyttää meidät asiaankuuluvissa käyttäjien kohtauslistoissa (kuten help_advanced – komento). Meidän ei tarvitse asettaa USAGE_foo vaikka koska help_foo funktio tekee sen meille.

piilottamalla komennot

Jos komento ei ole vielä valmis ”prime timeen”, haluat ehkä sen crosh: ssa varhaista testausta varten, mutta se ei näy help ulostulossa, josta käyttäjät voivat helposti löytää sen (koodi on tietenkin julkinen, joten kuka tahansa varsinaista lähdettä lukeva voi löytää sen). Näin se tehdään.

# Set the vars to pass the unittests ...USAGE_vmc=''HELP_vmc=''# ... then unset them to hide the command from "help" output.unset USAGE_vmc HELP_vmccmd_vmc() ( ...)